Extole Persons API

openapi: 3.0.1
info:
  description: 'Consumer-to-Extole integration endpoints: consumer event submission, zone rendering, profile management, and SDK-backing operations for browser and native app environments.'
  title: Integration API - Consumer to Extole Audiences Persons API
  version: '1.0'
servers:
- description: Production
  url: https://{brand}.extole.io
  variables:
    brand:
      default: yourcompany
      description: Your Extole client subdomain (e.g. 'mycompany' for mycompany.extole.io)
security:
- HEADER: []
- QUERY: []
- COOKIE: []
tags:
- name: Persons
paths:
  /api/v4/person/profile-picture-url/{personId}:
    get:
      deprecated: true
      description: Deprecated. Use `GET /api/v4/persons/{personId}/profile-picture-url` instead. Returns the profile picture URL for the person identified by `personId` as plain text.
      operationId: getPersonProfilePictureUrlV4
      parameters:
      - in: path
        name: personId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            text/plain:
              schema:
                type: string
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                invalid_person_id:
                  $ref: '#/components/examples/invalid_person_id'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                expired_access_token:
                  $ref: '#/components/examples/expired_access_token'
                invalid_access_token:
                  $ref: '#/components/examples/invalid_access_token'
                invalid_length_first_name:
                  $ref: '#/components/examples/invalid_length_first_name'
                invalid_length_last_name:
                  $ref: '#/components/examples/invalid_length_last_name'
                invalid_person_email:
                  $ref: '#/components/examples/invalid_person_email'
                invalid_profile_picture_url:
                  $ref: '#/components/examples/invalid_profile_picture_url'
                jwt_authentication_error:
                  $ref: '#/components/examples/jwt_authentication_error'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
                partner_user_id_already_defined:
                  $ref: '#/components/examples/partner_user_id_already_defined'
                partner_user_id_invalid_length:
                  $ref: '#/components/examples/partner_user_id_invalid_length'
                person_email_already_defined:
                  $ref: '#/components/examples/person_email_already_defined'
                person_not_found:
                  $ref: '#/components/examples/person_not_found'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Get a person's profile picture URL (legacy)
      tags:
      - Persons
      x-extole-bundle: integration-consumer-to-extole
      x-extole-visibility: visible
  /api/v4/person/{personId}:
    get:
      deprecated: true
      description: Deprecated. Use `GET /api/v4/persons/{personId}` instead. Returns the public profile for the person identified by `personId`.
      operationId: getPublicPersonV4
      parameters:
      - in: path
        name: personId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicPersonV4Response'
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                invalid_person_id:
                  $ref: '#/components/examples/invalid_person_id'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                expired_access_token:
                  $ref: '#/components/examples/expired_access_token'
                invalid_access_token:
                  $ref: '#/components/examples/invalid_access_token'
                invalid_length_first_name:
                  $ref: '#/components/examples/invalid_length_first_name'
                invalid_length_last_name:
                  $ref: '#/components/examples/invalid_length_last_name'
                invalid_person_email:
                  $ref: '#/components/examples/invalid_person_email'
                invalid_profile_picture_url:
                  $ref: '#/components/examples/invalid_profile_picture_url'
                jwt_authentication_error:
                  $ref: '#/components/examples/jwt_authentication_error'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
                partner_user_id_already_defined:
                  $ref: '#/components/examples/partner_user_id_already_defined'
                partner_user_id_invalid_length:
                  $ref: '#/components/examples/partner_user_id_invalid_length'
                person_email_already_defined:
                  $ref: '#/components/examples/person_email_already_defined'
                person_not_found:
                  $ref: '#/components/examples/person_not_found'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Get a public person profile (legacy)
      tags:
      - Persons
      x-extole-bundle: integration-consumer-to-extole
      x-extole-visibility: visible
  /v5/persons:
    get:
      description: Searches for persons by identity key value or client-defined person keys (supply in `name:value` format, e.g. `partner_conversion_id:abc123`). Returns an array because the same key may resolve to multiple Extole profiles. Supply at least one search criterion via query parameters.
      operationId: searchPersons
      parameters:
      - in: query
        name: identity_key_value
        schema:
          type: string
      - in: query
        name: person_keys
        schema:
          items:
            type: string
          type: array
      - in: query
        name: limit
        schema:
          format: int32
          type: integer
      - in: query
        name: offset
        schema:
          format: int32
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/PersonResponse'
                type: array
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Search for persons
      tags:
      - Persons
      x-extole-bundle: integration-server-to-extole
      x-extole-visibility: visible
    post:
      description: Creates a new person profile in the Extole platform and returns the persisted record with its server-assigned id. Use this to provision person profiles outside of the normal event-tracking flow (e.g. bulk imports).
      operationId: createPerson_2
      requestBody:
        content:
          application/json:
            example:
              identity_key_value: identity_key_value
            schema:
              $ref: '#/components/schemas/PersonRequest'
        description: PersonRequest object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonResponse'
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                forward_to_profile_is_device:
                  $ref: '#/components/examples/forward_to_profile_is_device'
                forwarding_profile_is_device:
                  $ref: '#/components/examples/forwarding_profile_is_device'
                identity_key_value_already_taken:
                  $ref: '#/components/examples/identity_key_value_already_taken'
                invalid_block_reason:
                  $ref: '#/components/examples/invalid_block_reason'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_key_value:
                  $ref: '#/components/examples/invalid_key_value'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
                person_not_found:
                  $ref: '#/components/examples/person_not_found'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Create a person
      tags:
      - Persons
      x-extole-bundle: integration-server-to-extole
      x-extole-visibility: visible
  /v5/persons/partner-keys:
    get:
      description: Returns the set of partner key names configured for the calling client. Partner keys are client-defined person identifier types (e.g. `partner_conversion_id`, `partner_shipment_id`) that supplement Extole's built-in identifiers. Supply the optional `include_campaign_ignoring_state` parameter to include partner keys declared in a specific campaign regardless of that campaign's state.
      operationId: getPartnerKeys_2
      parameters:
      - description: Include partner keys of the specified campaign, ignoring state
        in: query
        name: include_campaign_ignoring_state
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  type: string
                type: array
                uniqueItems: true
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: List partner keys
      tags:
      - Persons
      x-extole-bundle: integration-server-to-extole
      x-extole-visibility: visible
  /v5/persons/{person_id}:
    get:
      description: Returns the person profile for the specified `person_id`. The response includes the person's current identity key and value, locale settings, and version. Returns `403 person_not_found` if the person does not exist or is not accessible.
      operationId: getPerson_3
      parameters:
      - description: The Extole unique profile identifier of this user at Extole.
        in: path
        name: person_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonResponse'
          description: Person profile.
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                person_not_found:
                  $ref: '#/components/examples/person_not_found'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Person was not found or is not accessible to the calling client.
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Get a person
      tags:
      - Persons
      x-extole-bundle: integration-server-to-extole
      x-extole-visibility: visible
    put:
      description: Updates the identity key value on the specified person profile. Returns `403 person_not_found` if the person does not exist or is not accessible.
      operationId: updatePerson_2
      parameters:
      - description: Id for person to be updated
        in: path
        name: person_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              identity_key_value: identity_key_value
            schema:
              $ref: '#/components/schemas/PersonRequest'
        description: PersonRequest object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonResponse'
          description: Updated person profile.
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                forward_to_profile_is_device:
                  $ref: '#/components/examples/forward_to_profile_is_device'
                forwarding_profile_is_device:
                  $ref: '#/components/examples/forwarding_profile_is_device'
                identity_key_value_already_taken:
                  $ref: '#/components/examples/identity_key_value_already_taken'
                invalid_block_reason:
                  $ref: '#/components/examples/invalid_block_reason'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_key_value:
                  $ref: '#/components/examples/invalid_key_value'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                person_not_found:
                  $ref: '#/components/examples/person_not_found'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Person was not found or is not accessible to the calling client.
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Update a person
      tags:
      - Persons
      x-extole-bundle: integration-server-to-extole
      x-extole-visibility: visible
  /v5/persons/{person_id}/block:
    get:
      description: Returns the block record for the specified person, indicating whether they are blocked from participating in referral campaigns and the reason for the block.
      operationId: getPersonBlock
      parameters:
      - description: The Extole unique profile identifier of this user at Extole.
        in: path
        name: person_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonBlockResponse'
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
                person_not_found:
                  $ref: '#/components/examples/person_not_found'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Get person block status
      tags:
      - Persons
      x-extole-bundle: integration-server-to-extole
      x-extole-visibility: visible
    put:
      description: Updates the block record for the specified person. Set `type` to `EVENTS` to block event participation, `REWARDS` to block reward fulfilment, or `NONE` to remove any block. Supply an optional `reason` string for audit purposes. Returns the updated block record.
      operationId: updatePersonBlock
      parameters:
      - description: The Extole unique profile identifier of this user at Extole.
        in: path
        name: person_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              reason: reason
              type: EVENTS
            schema:
              $ref: '#/components/schemas/PersonBlockRequest'
        description: PersonBlockRequest object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonBlockResponse'
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                forward_to_profile_is_device:
                  $ref: '#/components/examples/forward_to_profile_is_device'
                forwarding_profile_is_device:
                  $ref: '#/components/examples/forwarding_profile_is_device'
                identity_key_value_already_taken:
                  $ref: '#/components/examples/identity_key_value_already_taken'
                invalid_block_reason:
                  $ref: '#/components/examples/invalid_block_reason'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_key_value:
                  $ref: '#/components/examples/invalid_key_value'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                metho

# --- truncated at 32 KB (197 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/extole/refs/heads/main/openapi/extole-persons-api-openapi.yml