Please enable JavaScript to view this website.

Skip to main content

API

The JEDI team provides and maintains a Web API that allows for easily allocating, updating, and retrieving end user information.

OpenAPI Specification​

Detailed Developer Documentation

The full list of available endpoints and how to use them can be found within the API documentation here.

EU360 Internal Site

Comprehensive platform details or in-depth documentation regarding EU 360 can be found here.

Below, we provide several examples of common operations with the CDP APIs.

Customer Data Platform​

In today's data-driven world, access to accurate and up-to-date customer information is paramount for businesses to provide personalized experiences, improve customer engagement, and drive growth. The Customer Data Platform (CDP) API plays a pivotal role in enabling developers to harness the power of customer data.

Why is the CDP API Important for Developers?​

The CDP API serves as a bridge between applications and a centralized repository of customer data, allowing developers to seamlessly integrate and utilize this valuable information in their software solutions. Here's why the CDP API is essential for developers:

1. Real-Time Data Access​

The CDP API provides developers with real-time access to customer data. Whether you need to retrieve user profiles, transaction history, or preferences, the API ensures that you always have the latest information at your fingertips.

2. Personalization​

Personalization is at the heart of delivering exceptional customer experiences. With the CDP API, developers can retrieve detailed customer profiles, including demographic data, preferences, and behavioral insights. This data empowers developers to create tailored experiences that resonate with each individual user.

3. Integration Capabilities​

Developers often work with a variety of software applications and systems. The CDP API simplifies the integration process, allowing developers to connect customer data to their applications, marketing automation platforms, or analytics tools seamlessly.

4. Data Security​

Data security and compliance are critical concerns in the digital age. The CDP API is designed with security in mind, ensuring that customer data remains protected and that access is granted only to authorized users and applications.

5. Improved Customer Insights​

Access to a comprehensive view of customer interactions and preferences enables developers to gain deeper insights into customer behavior. This knowledge can inform decision-making and strategy, ultimately leading to better customer engagement and business outcomes.

In this documentation, we will explore specific API endpoints and data structures, starting with the "GetUserByEmail" request as an example. By understanding how to effectively use the CDP API, developers can unlock the full potential of customer data to drive innovation and create exceptional customer experiences.

Overview​

The cdp-api allows developers to interact with our Customer Data Platform programmatically. With these endpoints, you can create, retrieve, and search user profiles, leveraging the wealth of customer data stored in our platform. This documentation covers the following key endpoints:

  • Get User Profile (GET /v1/user)
  • Create User (POST /v1/user)
  • User Search (GET /v1/user/search)

Get User Profile​

GET /v1/user​

This endpoint supports querying for an end user using various identifiers.

Parameters:

  • id (string, optional): A unique identifier of the user profile you wish to retrieve (e.g., email, identity vertex id, auth0 account id, etc.)

Responses:

  • 200: Success Response. Returns the user profile data.
  • 400: Bad Request. Error response with additional context property.
  • 401: Unauthorized. Invalid or missing access token.
  • 403: Forbidden. Invalid or missing API key (not implemented).
  • 404: NotFound. User not found.
  • 500: Internal Server Error.

Example Request:

GET /v1/user?id=unique-user-id

Create User​

You MUST send an identify event to RudderStack using the returned identityId to complete the user creation process. This ensures the user profile is created in the data warehouse as well as the graph database.

POST /v1/user​

This endpoint creates a new user with the provided details.

Request Body:

  • Provide user details such as emailAddress, firstName, lastName, phoneNumber, address1, address2, city, state, postalCode, country, jobTitle, languagePreference, trade, tradeSector, secondaryTradeSectors. Note: The request body is optional. If no request body is provided, the user profile will be created with only an id field. If a request body is provided, those fields will be saved as part of the profile on initial profile creation. Responses:

  • 201: User created successfully.

  • 400: Bad Request. Error response with additional context property.

  • 401: Unauthorized. Invalid or missing access token.

  • 403: Forbidden. Invalid or missing API key (not implemented).

  • 500: Internal Server Error.

Example Request With Request Body:

POST /v1/user
{
  "emailAddress": "john@example.com",
  "firstName": "John",
  "lastName": "Doe",
  // additional user details, see schema for full list of fields
}

GET /v1/user/search​

This endpoint allows you to search for users by name or phone number, returning a list of matching users.

Parameters:

  • phone (string, optional): Phone number to query by.
  • name (string, optional): Full name to query by in URL-encoded format (e.g., "John%20Doe").

Responses:

  • 200: Successful operation. Returns a list of matching user profiles.
  • 400: Bad Request. Error response with additional context property.
  • 401: Unauthorized. Invalid or missing access token.
  • 403: Forbidden. Invalid or missing API key (not implemented).
  • 500: Internal Server Error.

Example Request:

GET /v1/user/search?name=John%20Doe

Get User Profile Request

Request Details​

  • HTTP Method: GET

Request Headers​

  • Content-Type: Application/Json
  • Authorization: Bearer {access_token} (required)
  • x-api-key: {api_key} (optional for now - will be required in the future)

Example Request JSON​

  • https://cdp-api-test.milwaukeetool.com/v1/user?phone=4141112222

Response Details​

Response Body​

{
  "data": {
    "identity": {
      "emailAddress": "john@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "address1": "456 S. Main St",
      "address2": "#101",
      "city": "Milwaukee",
      "state": "Wisconsin",
      "country": "US",
      "postalCode": "53211",
      "phoneNumber": "4141112222",
      "jobTitle": "superintendent",
      "trade": "carpentry",
      "tradeSector": "commercial",
      "secondaryTradeSectors": ["residential", "industrial"],
      "languagePreference": "English",
      "createdAt": 1691774580629,
      "updatedAt": 1691774580629
    },
    "axId": "00000000-0000-0000-0000-000000000005",
    "hubspotId": "00000000-0000-0000-0000-000000000001",
    "oneKeyId": "00000000-0000-0000-0000-000000000003",
    "brazeId": "00000000-0000-0000-0000-000000000002",
    "d365ContactId": "00000000-0000-0000-0000-000000000004",
    "d365ContactGroup": "marketing",
    "d365ContactType": "distributor",
    "auth0Accounts": [
      {
        "id": "auth0|1234567890",
        "legacyUserId": "legacy-id-for-accounts-db-proxy",
        "emailVerified": true,
        "connection": "accounts-db-proxy"
      },
      {
        "id": "waad|1234567890",
        "legacyUserId": "legacy-id-for-milwaukeetool-waad",
        "emailVerified": true,
        "connection": "milwaukeetool-waad"
      }
    ],
    "marketingPreferences": {
      "cookieOptIn": false,
      "subscribedHDNewsEmail": true,
      "subscribedOneKeyNewsletterEmail": true,
      "subscribedConnectEmail": false,
      "subscribedGridEmail": false,
      "subscribedResearchEmail": false,
      "subscribedHDNewsText": false,
      "subscribedHDCenterEmail": false,
      "subscribedHDCenterText": false,
      "subscribedGridText": false,
      "createdAt": 1691774580629,
      "updatedAt": 1691774580629
    },
    "company": {
      "name": "Acme Corp",
      "address1": "123 Fake Street",
      "address2": "Apt 456",
      "city": "Faketown",
      "state": "WI",
      "postalCode": "12345",
      "country": "USA",
      "size": "1000",
      "createdAt": 1691774580629,
      "updatedAt": 1691774580629
    },
    "products": ["48-32-4013", "2851-20"],
    "hdaAccount": {
      "number": "123456789",
      "name": "account_name",
      "partnerClassification": "transactional",
      "hdaStatus": "hda_status",
      "hdaPceNumber": "hda_pce_numberj",
      "hdaEffectiveDate": "1/1/2025",
      "hdaEndDate": "1/1/2026"
    }
  }
}

Get Moments

Request Headers​

  • Content-Type: Application/Json
  • Authorization: Bearer {access_token} (required)
  • x-api-key: {api_key} (optional for now - will be required in the future)

Parameters:

  • userId (string, required): A unique identifier of the user for which to retrieve moments.
  • types (array, optional): Filter by one or more moment types.
  • view (string, optional): Selects the result mode. Use latestPerCase to return exactly one latest moment per caseId. Omit for default behavior (all moments).
  • orderby (string, optional): Sort direction. Supported directions: asc, desc. Defaults to desc. In view=latestPerCase, sorting is applied to the selected per-case moments.
  • page (integer, optional): The page number (1-based). Defaults to 1.
  • resultsperpage (integer, optional): Number of items per page. Defaults to 25. In view=latestPerCase, this is the number of cases returned.

Example Request:

GET /v1/moments?userId=00000000-0000-0000-0000-000000000005&types=cx_case_management_v2&orderby=desc&page=1&resultsperpage=10

Example Request URL​

  • https://cdp-api-test.milwaukeetool.com/v1/moments?userId=00000000-0000-0000-0000-000000000005&types=cx_case_management_v2&orderby=desc&page=1&resultsperpage=10

Response Details​

Response Body​

{
  "data": 
  {
    "userId": "00000000-0000-0000-0000-000000000005",
    "email": "john@example.com",
    "phoneNumber": "4141112222",
    "firstName": "John",
    "lastName": "Doe",
    "page": 1,
    "pageSize": 10,
    "totalCount": 100,
    "totalPages": 10,
    "moments": [
      {
          "eventChannel": "Email",
          "eventCaseOpenedDate": "2024-01-20 20:53:28",
          "status": "Resolved",
          "contextSystemOfRecord": "service_now",
          "eventAssignmentGroup": "CX Digital Solutions",
          "eventCaseCategory": "Pricing/Availability",
          "eventCaseState": "Closed",
          "contextEventCategory": "cx_case_management",
          "contextLocation": "service_now",
          "eventCaseResolution": "Resolved by CX Support",
          "eventCaseNumber": "CS000012546"
      },
      { 
          "eventChannel": "Email",
          "eventCaseOpenedDate": "2024-01-18 20:53:28",
          "status": "In Progress",
          "contextSystemOfRecord": "service_now",
          "eventAssignmentGroup": "CX Digital Solutions",
          "eventCaseCategory": "Pricing/Availability",
          "eventCaseState": "In Progress",
          "contextEventCategory": "cx_case_management",
          "contextLocation": "service_now",
          "eventCaseResolution": "Resolved by CX Support",
          "eventCaseNumber": "CS000012547"
      }
    ],
     "page": 1,
     "pageSize": 10,
     "totalCount": 100,
     "totalPages": 10,
  }
}

Get Moments by type

Request Headers​

  • Content-Type: Application/Json
  • Authorization: Bearer {access_token} (required)
  • x-api-key: {api_key} (optional for now - will be required in the future)

Parameters:

  • momentType (string, required, path): The type of moment to retrieve (e.g. cx_case_management_v2, auth0_log_in_v1).
  • userId (string, optional): A unique identifier of the user for which to retrieve moments.
  • caseId (string, optional): Filter moments by case ID.
  • page (integer, optional): The page number. Defaults to 1.
  • resultsperpage (integer, optional): Number of items per page. Defaults to 25.

Example Request:

GET /v1/moments/{momentType}?userId=00000000-0000-0000-0000-000000000005&caseId=12345&page=1&resultsperpage=25

Example Request URL​

  • https://cdp-api-test.milwaukeetool.com/v1/moments/cx_case_management_v2?userId=00000000-0000-0000-0000-000000000005&caseId=12345&page=1&resultsperpage=25
{
  "data":  [
    {
      "userId": "00000000-0000-0000-0000-000000000005",
      "email": "john@example.com",
      "phoneNumber": "4141112222",
      "firstName": "John",
      "lastName": "Doe",
      "page": 1,
      "pageSize": 10,
      "totalCount": 100,
      "totalPages": 10,
      "moments": [
        {
          "eventChannel": "Email",
          "eventCaseOpenedDate": "2024-01-18 20:53:28",
          "status": "Resolved",
          "contextSystemOfRecord": "service_now",
          "eventAssignmentGroup": "CX Digital Solutions",
          "eventCaseCategory": "Pricing/Availability",
          "eventCaseState": "Closed",
          "contextEventCategory": "cx_case_management",
          "contextLocation": "service_now",
          "eventCaseResolution": "Resolved by CX Support",
          "eventCaseNumber": "CS000012546"
        },
        {
          "eventDate": 1696251000,
          "eventChannel": "Email",
          "eventCaseOpenedDate": "2024-01-18 20:53:28",
          "status": "In Progress",
          "contextSystemOfRecord": "service_now",
          "eventAssignmentGroup": "CX Digital Solutions",
          "eventCaseCategory": "Pricing/Availability",
          "eventCaseState": "In Progress",
          "contextEventCategory": "cx_case_management",
          "contextLocation": "service_now",
          "eventCaseNumber": "CS000012546"
        },
        {
          "eventDate": 1696251000,
          "eventChannel": "Email",
          "eventCaseOpenedDate": "2024-01-18 20:53:28",
          "status": "Open",
          "contextSystemOfRecord": "service_now",
          "eventAssignmentGroup": "CX Digital Solutions",
          "eventCaseCategory": "Pricing/Availability",
          "eventCaseState": "Open",
          "contextEventCategory": "cx_case_management",
          "contextLocation": "service_now",
          "eventCaseNumber": "CS000012546"
        }
      ]
    }
  ]
}

API Error Handling​

This documentation outlines the error responses that can be expected from the API. Errors are communicated through specific codes and messages that indicate the type of issue encountered during the request processing.

Error Codes​

The API uses a set of predefined error codes to indicate various errors that can occur during the request lifecycle. Below is a table describing each error code, the HTTP status code returned, and a brief description of the scenario under which the error might be triggered.

Error CodeHTTP Status CodeDescription
ERR0001404Indicates that the specified resource was not found.
ERR0002500Indicates an unhandled exception occurred in the API.
ERR0003400Returned when the request contains bad syntax or cannot be fulfilled.
ERR0004403Indicates that the request was valid but the server is refusing action due to lack of permissions.
ERR0005409Indicates a duplicate email error occurred during user registration or updating.
ERR0006400Indicates that required query parameters are missing or invalid.

Error Response Format​

Error responses are returned in JSON format with the following structure:

{
  "error": {
    "code": "ErrorCode",
    "message": "Detailed error message describing the error.",
    "context": "Contextual information or data related to the error.",
    "retryable": false
  }
}

Handling Errors in Your Application​

info

When consuming this API, it is recommended to implement error handling logic that interprets these error codes and messages appropriately, allowing your application to respond to different scenarios robustly. This may include retries for transient errors or user notifications for correction when input validation fails. The retryable property on the error object can be used to determine if the error is transient and can be retried. Please note that messages are not intented to be displayed to the end-user directly and are subject to change at any time. Client applications should take care to craft messages that are specific to the application domain.

Security​

All endpoints are protected and require appropriate authentication. Currently, an Authorization header in the format of Bearer {token} is required. In the future, an x-api-key header will also be required.

Please refer to this documentation while integrating with the cdp-api. For further details or assistance, contact our development support team at jedi-data-engineering @ milwaukeetool.com.