CrossEngage
CrossEngage User Management API v2

Asynchronous customer profile API — create, update and delete single users, batch up to 1,000 users per call, look a user up by id or by email plus business unit, and poll a tracking id for terminal status. This is the primary data-in path for the CDP and the version CrossEngage recommends over v1. Six operations, published as an API Blueprint on Apiary. Requires the Master API key and X-XNG-ApiVersion: 2.
Documentation GitHub OpenAPI
OpenAPI Specification

swagger: '2.0'
info:
  title: User Management API v2
  version: '2.0'
  description: "## What is different in v2 comparing to v1?\n\nIn [v1 documentation](https://usermanagementv1.docs.apiary.io)\
    \ you can find following sections:\n\n* User Attribute Management\n\n* Lead management\n\n* User profile\
    \ management\n\n* Event management\n\n* Opt-out management\n\nIn v2 currently we only have **User\
    \ profile management**.\nThe main difference here is that v1 is synchronous and v2 is asynchronous.\n\
    \nManaging users asynchronously has a number of advantages, \nsuch as better stability and performance\
    \ under load,\nwhich means that you will not get processing timeouts even in times of high load.\n\
    We are also working hard on optimizing the performance of v2 \nand we expect it to be substantially\
    \ faster, than v1.\n\nSo it is recommended to use v2.\n\n## Authentication\n\nCrossEngage uses **header\
    \ authentication**.\nTo get your API key, please log into the [app](https://app.crossengage.io) and\
    \ navigate\nto **Settings -> System setup**. You will find the value in the **API keys** section\n\
    in the **Master API key** field.\n\n## Versioning\n\nThe versions of our different endpoints are defined\
    \ in the header `X-XNG-ApiVersion`. \nTo use this API please provide version **2**.\n\n## Headers\n\
    \nTo use the CrossEngage API, please provide the following header values \nwith each call you make:\n\
    \n* `X-XNG-AuthToken`\n\n* `X-XNG-ApiVersion`\n\n## Error handling\n\nIn case of request errors, CrossEngage\
    \ generates custom error codes within an error JSON response,\nto better describe what exactly caused\
    \ an error. Here a possible codes:\n\n* 1 - Invalid JSON\n\n* 2 - Invalid field value, or missing\
    \ a required field\n\n* 3 - Invalid attribute type\n\n* 4 - Invalid Email Format\n\n* 5 - Invalid\
    \ Phone Format\n\n* 6 - Unknown Attribute\n\n* 7 - Identifier Mismatch\n\n* 8 - Invalid Business Unit\
    \ Format\n\n* 9 - Max batch request size violation\n\n* 10 - Request processing failed, please contact\
    \ support\n\nFor error response examples, please check the specific endpoints sections.\n\nWhen calling\
    \ CrossEngage API, please use the following practices \nrelated to error handling.\n\nRetry calls\
    \ that fail due to connection interruptions or any `5xx` errors, \nincluding:\n\n* `500 Internal Server\
    \ Error`\n\n* `502 Bad gateway`\n\n* `503 Service Unavailable`\n\n* `504 Gateway Timeout`\n\nHow to\
    \ retry requests made to CrossEngage API in case of errors:\n\n* Use an [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff)\
    \ \nstrategy if any HTTP 5xx error is returned when calling the API. \nThese errors can occur if a\
    \ server is getting overloaded. \nExponential backoff can help alleviate these kinds of problems during\
    \ periods \nof high volume of requests or heavy network traffic.\n\n* Other kinds of error responses\
    \ should not be handled with exponential backoff \nbut you can still retry a number of them. \nWhen\
    \ retrying these requests, limit the number of times you do that. \nFor example your code could limit\
    \ to ten retries or less before reporting an error."
  x-apib-source: https://usermanagementv2.docs.apiary.io/api-description-document
host: api.crossengage.io
basePath: /
schemes:
- https
paths:
  /users/{id}:
    get:
      responses:
        '200':
          description: OK
          headers: {}
          examples:
            application/json;charset=UTF-8:
              email: john.doe@crossengage.io
              id: fb85fe50-a528-11e7-abc4-cec278b6b50a
              xngId: 123e4567-e89b-12d3-a456-426655440000
              firstName: John
              lastName: Doe
              birthday: '1982-08-30'
              createdAt: '2015-10-02T08:23:53Z'
              gender: male
          schema:
            type: object
            properties:
              email:
                type: string
              id:
                type: string
              xngId:
                type: string
              firstName:
                type: string
              lastName:
                type: string
              birthday:
                type: string
              createdAt:
                type: string
              gender:
                type: string
            example:
              email: john.doe@crossengage.io
              id: fb85fe50-a528-11e7-abc4-cec278b6b50a
              xngId: 123e4567-e89b-12d3-a456-426655440000
              firstName: John
              lastName: Doe
              birthday: '1982-08-30'
              createdAt: '2015-10-02T08:23:53Z'
              gender: male
        '404':
          description: User with a given `id` was not found.
          headers: {}
          examples: {}
      summary: Get a single user with id
      operationId: getASingleUserWithId
      description: ''
      tags:
      - User Profile Management
      parameters:
      - name: id
        in: path
        description: ID of the user in your database.
        required: true
        x-example: fb85fe50-a528-11e7-abc4-cec278b6b50a
        type: string
      - name: X-XNG-ApiVersion
        in: header
        description: e.g. 2
        required: false
        x-example: '2'
        type: string
      - name: X-XNG-AuthToken
        in: header
        description: e.g. YourAPIKey
        required: false
        x-example: YourAPIKey
        type: string
      produces:
      - application/json;charset=UTF-8
      consumes:
      - application/json
    delete:
      responses:
        '202':
          description: "Request was accepted and will be processed asynchronously. \nUse \n[request tracking](https://usermanagementv2.docs.apiary.io/#reference/user-profile-management/request-tracking)\
            \ \nendpoint with the provided tracking ID in order to check the request status."
          headers: {}
          examples: {}
      summary: Delete a single user
      operationId: deleteASingleUser
      description: "Please note, DELETE request for already deleted or non-existent users \nwill always\
        \ return success."
      tags:
      - User Profile Management
      parameters:
      - name: id
        in: path
        description: ID of the user in your database.
        required: true
        x-example: fb85fe50-a528-11e7-abc4-cec278b6b50a
        type: string
      - name: X-XNG-ApiVersion
        in: header
        description: e.g. 2
        required: false
        x-example: '2'
        type: string
      - name: X-XNG-AuthToken
        in: header
        description: e.g. YourAPIKey
        required: false
        x-example: YourAPIKey
        type: string
      consumes:
      - application/json
  /users/email/{email}/bu/{bu}:
    get:
      responses:
        '200':
          description: OK
          headers: {}
          examples:
            application/json;charset=UTF-8:
              email: john.doe@crossengage.io
              id: fb85fe50-a528-11e7-abc4-cec278b6b50a
              xngId: 123e4567-e89b-12d3-a456-426655440000
              firstName: John
              lastName: Doe
              birthday: '1982-08-30'
              createdAt: '2015-10-02T08:23:53Z'
              gender: male
          schema:
            type: object
            properties:
              email:
                type: string
              id:
                type: string
              xngId:
                type: string
              firstName:
                type: string
              lastName:
                type: string
              birthday:
                type: string
              createdAt:
                type: string
              gender:
                type: string
            example:
              email: john.doe@crossengage.io
              id: fb85fe50-a528-11e7-abc4-cec278b6b50a
              xngId: 123e4567-e89b-12d3-a456-426655440000
              firstName: John
              lastName: Doe
              birthday: '1982-08-30'
              createdAt: '2015-10-02T08:23:53Z'
              gender: male
        '404':
          description: User with a given input was not found.
          headers: {}
          examples: {}
      summary: Get a single user with email and bu
      operationId: getASingleUserWithEmailAndBu
      description: ''
      tags:
      - User Profile Management
      parameters:
      - name: email
        in: path
        description: Email of the user.
        required: true
        x-example: example@crossengage.io
        type: string
      - name: bu
        in: path
        description: Business Unit of the user.
        required: false
        x-example: BU
        type: string
      - name: X-XNG-ApiVersion
        in: header
        description: e.g. 2
        required: false
        x-example: '2'
        type: string
      - name: X-XNG-AuthToken
        in: header
        description: e.g. YourAPIKey
        required: false
        x-example: YourAPIKey
        type: string
      produces:
      - application/json;charset=UTF-8
      consumes:
      - application/json
  /users:
    put:
      responses:
        '202':
          description: "Request was accepted and will be processed asynchronously. \nUse \n[Request Tracking](https://usermanagementv2.docs.apiary.io/#reference/user-profile-management/request-tracking)\n\
            endpoint with the provided tracking ID \nin order to check request status."
          headers: {}
          examples:
            application/json;charset=UTF-8:
              trackingId: 2e312089-a987-45c6-adbd-b904bc4dfc97
          schema:
            type: object
            properties:
              trackingId:
                type: string
            example:
              trackingId: 2e312089-a987-45c6-adbd-b904bc4dfc97
        '400':
          description: "Request was not processed due to a validation error (see response).\n\nPlease\
            \ see the \n[Error Handling section](https://usermanagementv2.docs.apiary.io/#introduction/error-handling)\n\
            for possible validation errors."
          headers: {}
          examples: {}
        '401':
          description: Wrong or missing credentials.
          headers: {}
          examples: {}
        '500':
          description: Unknown error on our side.
          headers: {}
          examples: {}
      summary: Create/update a single user
      operationId: createUpdateASingleUser
      description: "It's required to provide both `id` and `email` in every query.\n\nIf you will provide\
        \ an `email`, which is different from the one, \ncurrently stored for this user, it will be updated.\n\
        \nIf you will provide a new `id`, but already existing `email`, \nyou will get a processing error\
        \ and the user will not be created."
      tags:
      - User Profile Management
      parameters:
      - name: X-XNG-ApiVersion
        in: header
        description: e.g. 2
        required: false
        x-example: '2'
        type: string
      - name: X-XNG-AuthToken
        in: header
        description: e.g. YourAPIKey
        required: false
        x-example: YourAPIKey
        type: string
      - name: body
        in: body
        schema:
          type: object
          properties:
            id:
              type: string
              description: User identifier in your database
            email:
              type: string
              description: User e-mail
            businessUnit:
              type: string
              description: Your company's business unit, to which this user is attached, only relevant
                if you have multiple business units set up in your CrossEngage account, in other cases,
                it may be null
            lastName:
              type: string
              description: Custom user's attribute
            age:
              type: number
              description: Custom user's attribute
            '...':
              type: string
              description: Any other custom user attributes defined for your company
          required:
          - id
          - email
          example:
            id: 31d29083-b3ad-4864-9d0c-dc20a9fa72c8
            email: john.doe@crossengage.io
            firstName: John
            lastName: Doe
            birthday: '1982-08-30'
            createdAt: '2015-10-02T08:23:53Z'
            gender: male
            businessUnit: DE
      produces:
      - application/json;charset=UTF-8
      consumes:
      - application/json
  /users/batch:
    post:
      responses:
        '202':
          description: "In case of validation error(s) for any elements in batch. \nAll valid entries\
            \ will be processed. Use \n[Request Tracking](https://usermanagementv2.docs.apiary.io/#reference/user-profile-management/request-tracking)\n\
            endpoint with the provided tracking ID in order to check the request status.\n\nPlease see\
            \ the \n[Error Handling section](https://usermanagementv2.docs.apiary.io/#introduction/error-handling)\n\
            for possible validation errors."
          headers: {}
          examples: {}
          schema:
            type: object
            properties:
              errors:
                type: array
                description: errors
                items: {}
            required:
            - errors
        '400':
          description: In case of max batch request size violation
          headers: {}
          examples:
            application/json:
              errors:
              - code: '9'
                title: Max batch request size violation
                details: Max batch request size is 1,000, but was 5,000
                info: https://docs.crossengage.io/errors#9
                source:
                  pointer: /updated
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  type: object
                  properties:
                    code:
                      type: string
                    title:
                      type: string
                    details:
                      type: string
                    info:
                      type: string
                    source:
                      type: object
                      properties:
                        pointer:
                          type: string
            example:
              errors:
              - code: '9'
                title: Max batch request size violation
                details: Max batch request size is 1,000, but was 5,000
                info: https://docs.crossengage.io/errors#9
                source:
                  pointer: /updated
      summary: Create/update/delete multiple users
      operationId: createUpdateDeleteMultipleUsers
      description: "For more information about how individual users are processed,\nplease check the \n\
        [delete a single user](https://usermanagementv2.docs.apiary.io/#reference/user-profile-management/getdelete-a-single-user/delete-a-single-user)\
        \ \nand \n[create/update](https://usermanagementv2.docs.apiary.io/#reference/user-profile-management/createupdate-a-single-user)\
        \ \na single user sections of this doc."
      tags:
      - User Profile Management
      parameters:
      - name: X-XNG-ApiVersion
        in: header
        description: e.g. 2
        required: false
        x-example: '2'
        type: string
      - name: X-XNG-AuthToken
        in: header
        description: e.g. YourAPIKey
        required: false
        x-example: YourAPIKey
        type: string
      - name: body
        in: body
        schema:
          type: object
          properties:
            updated:
              type: array
              description: A list of users to batch create/update
            deleted:
              type: array
              description: A list of users to batch delete
          example:
            updated:
            - email: john.doe@crossengage.io
              id: fb85fe50-a528-11e7-abc4-cec278b6b50a
              firstName: John
              lastName: Doe
              birthday: '1982-08-30'
              createdAt: '2015-10-02T08:23:53Z'
              gender: male
            deleted:
            - email: jane.doe@crossengage.io
              id: '1234'
              firstName: Jane
              lastName: Doe
              birthday: '1982-08-30'
              createdAt: '2015-10-02T08:23:53Z'
              gender: female
      produces:
      - application/json
      consumes:
      - application/json
  /users/track/{trackingId}:
    get:
      responses:
        '200':
          description: OK
          headers: {}
          examples:
            application/json:
              stage: PROCESSED
              total: 2
              success: 1
              error: 1
          schema:
            type: object
            properties:
              stage:
                type: string
                description: '**PENDING** - request waiting to be processed, **PROCESSED** - request already
                  processed'
              total:
                type: string
                description: Total number of users in the bulk request
              success:
                type: string
                description: Number of users who were processed sucesfully
              error:
                type: string
                description: Number of users who can't be processed due to errors
        '404':
          description: Requested tracking information was not found because trackingId is unknown or expired.
          headers: {}
          examples: {}
      summary: Retrieve status
      operationId: retrieveStatus
      description: ''
      tags:
      - User Profile Management
      parameters:
      - name: X-XNG-ApiVersion
        in: header
        description: e.g. 2
        required: false
        x-example: '2'
        type: string
      - name: X-XNG-AuthToken
        in: header
        description: e.g. YourAPIKey
        required: false
        x-example: YourAPIKey
        type: string
      produces:
      - application/json
      consumes:
      - application/json
definitions:
  Get/Delete a Single User: {}
  Get a Single User with email and bu: {}
  Create/Update a Single User: {}
  Bulk User Management: {}
  Request tracking: {}
  UserBatchAttributes:
    type: object
    properties:
      updated:
        type: array
        items: {}
        description: A list of users to batch create/update
      deleted:
        type: array
        items: {}
        description: A list of users to batch delete
  UserAttributes:
    type: object
    required:
    - id
    - email
    properties:
      id:
        type: string
        example: 31d29083-b3ad-4864-9d0c-dc20a9fa72c8
        description: User identifier in your database
      email:
        type: string
        example: john.doe@crossengage.io
        description: User e-mail
      businessUnit:
        type: string
        example: DE
        description: Your company's business unit, to which this user is attached, only relevant if you
          have multiple business units set up in your CrossEngage account, in other cases, it may be null
      lastName:
        type: string
        example: Doe
        description: Custom user's attribute
      age:
        type: number
        example: 25
        description: Custom user's attribute
      '...':
        type: string
        description: Any other custom user attributes defined for your company
  UserAttributesError:
    type: object
    required:
    - errors
    properties:
      errors:
        type: array
        items: {}
        description: errors
  ErrorObj:
    type: object
    required:
    - code
    properties:
      code:
        type: string
        description: 'Internal code to uniquely identify the error type. Please see the


          [Error Handling section](https://usermanagementv2.docs.apiary.io/#introduction/error-handling)

          for possible validation errors.'
      title:
        type: string
        description: Human readable string to describe the error type
      details:
        type: string
        description: Human readable string to describe specific details of the error
      info:
        type: string
        description: For future use, currently not implemented.
      source:
        type: object
        properties:
          pointer:
            type: string
            description: JSON pointer to the attribute that caused the error
        description: Contains information about what caused the error
securityDefinitions:
  XngAuthToken:
    type: apiKey
    name: X-XNG-AuthToken
    in: header
    description: CrossEngage header authentication. The API key is issued in the CrossEngage app under
      Settings -> System setup -> API keys (Master API key or Public API key depending on the API).
tags:
- name: User Profile Management
security:
- XngAuthToken: []
x-apievangelist:
  generated: '2026-08-13'
  method: derived
  source: blueprint/crossenagage-user-management-v2.apib
  note: Mechanically converted from the API Blueprint CrossEngage publishes at https://usermanagementv2.docs.apiary.io/api-description-document
    using apib2swagger. Verbatim blueprint retained at blueprint/. API Evangelist normalized operationIds
    to camelCase, declared the documented X-XNG-AuthToken header auth as a securityDefinition, and added
    the documented X-XNG-ApiVersion header parameter. No operations, paths, schemas or examples were invented.
CrossEngage User Management API v2

Documentation

Specifications

Other Resources

OpenAPI Specification
