openapi: 3.2.0
info:
  title: User Management API v1 Lead management API
  version: '1.0'
  description: 'The host of all of the URLs defined in this documentation is `https://api.documentation.crossengage.io`.


    ## Authentication


    CrossEngage uses **header authentication**.

    To obtain your API key, log in to the [app](https://app.crossengage.io) and select **System setup** from the **Settings** dropdown. Copy the Master API value from the **API keys** section of the **System setup** page.


    ## Versions


    The API version is defined in the header `X-XNG-ApiVersion`. This documentation displays endpoints for version 1.


    ## Headers


    To use the CrossEngage API, define the following header values for each call made:

    `X-XNG-AuthToken`, `X-XNG-ApiVersion`.


    ## Date Format


    Dates and times are expressed in ISO8601 format in UTC (Coordinated Universal Time), with a special UTC designator ("Z")

    For more information please check [here](https://www.w3.org/TR/NOTE-datetime).


    ## Error Handling


    Resume or retry uploads that fail due to connection interruptions or `5xx` errors such as the following:


    * `500 Internal Server Error`


    * `502 Bad Gateway`


    * `503 Service Unavailable`


    * `504 Gateway Timeout`


    How to retry CrossEngage API requests in case of errors:


    * Use an [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff) strategy if an export request returns a 5xx server error. These errors can occur if a server is overloaded. Exponential backoff can alleviate such problems during periods of high request volume or heavy network traffic.


    * For other kinds of requests, do not use exponential backoff. Instead, retry a limited number of the desired requests.'
  x-apib-source: https://usermanagementv1.docs.apiary.io/api-description-document
servers:
- url: https://api.crossengage.io/
security:
- XngAuthToken: []
tags:
- name: Lead management
paths:
  /leads/:
    post:
      responses:
        '200':
          description: The lead was processed successfully
          headers: {}
          content:
            application/json;charset=UTF-8:
              schema:
                type: object
                properties:
                  updated:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        xngId:
                          type: string
                        success:
                          type: boolean
                  deleted:
                    type: array
                    items: {}
                example:
                  updated:
                  - id: '1234'
                    xngId: '1234'
                    success: true
                  deleted: []
              example:
                updated:
                - id: '1234'
                  xngId: '1234'
                  success: true
                deleted: []
        '400':
          description: Lead was not processed due to a validation error (see response)
          headers: {}
          content:
            application/json;charset=UTF-8:
              schema:
                type: object
                properties:
                  updated:
                    type: array
                    items:
                      type: object
                      properties:
                        xngId:
                          type: string
                        success:
                          type: boolean
                        errors:
                          type: array
                          items:
                            type: object
                            properties:
                              field:
                                type: string
                              type:
                                type: string
                  deleted:
                    type: array
                    items: {}
                example:
                  updated:
                  - xngId: xng-id
                    success: false
                    errors:
                    - field: email
                      type: WRONG_FORMAT
                  deleted: []
              example:
                updated:
                - xngId: xng-id
                  success: false
                  errors:
                  - field: email
                    type: WRONG_FORMAT
                deleted: []
        '401':
          description: Wrong or missing credentials
          headers: {}
          content: {}
        '500':
          description: Unknown error on our side
          headers: {}
          content: {}
      summary: Create & update a lead
      operationId: createUpdateALead
      description: "This endpoint lets you create or update leads.\nThe system searches for existing leads based on records with email \naddresses and optionally business units. \nIn case a record with the requested identifiers exists, the lead is updated. \nOtherwise, a new lead will be created."
      tags:
      - Lead management
      parameters:
      - name: X-XNG-ApiVersion
        in: header
        description: e.g. 1
        required: false
        x-example: '1'
        schema:
          type: string
      - name: X-XNG-AuthToken
        in: header
        description: e.g. Your API Key
        required: false
        x-example: Your API Key
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  description: The lead's email
                businessUnit:
                  type: string
                  description: The business unit of the lead
                firstName:
                  type: string
                  description: The lead's first name
                lastName:
                  type: string
                  description: The lead's last name
                gender:
                  type: string
                  description: The lead's gender
                createdAt:
                  type: string
                  description: The date the user was created in your database
              required:
              - email
              example:
                updated:
                - id: '1234'
                  email: john.doe@crossengage.io
                  businessUnit: US
                  firstName: John
                  lastName: Doe
                  age: 21
                  gender: male
components:
  securitySchemes:
    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).
x-apievangelist:
  generated: '2026-08-13'
  method: derived
  source: blueprint/crossenagage-user-management-v1.apib
  note: Mechanically converted from the API Blueprint CrossEngage publishes at https://usermanagementv1.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.