Ometria Profiles API

openapi: 3.2.0
info:
  version: 1.1.0
  title: Ometria data Profiles API
  description: 'Welcome to the Ometria API reference.


    The Ometria API is organized around the REST methodology, and it uses resource-oriented URLs, and common HTTP response codes to indicate API errors. All requests are authenticated using an API key which can be obtained from your account settings.


    ### HTTPS


    All requests to the Ometria API MUST be carried out via HTTPS. API servers do not listen on unsecured HTTP ports to avoid the possibility of insecure information exchange.


    ### Message encoding


    The V2 Ometria API uses JSON encoding for all data exchanges and assumes UTF-8 character encoding throughout.


    ### Rate limits


    The Ometria API has a default rate limit of 4 requests per second per Ometria account. The /push/ endpoint allows 8 requests per second per Ometria account. If you expect to exceed this limit, please contact us.


    In the case of your application being rate limited, the HTTP code 429 (too many requests) will be returned. In this case your application should reduce the number of requests it is trying to send.'
  contact:
    name: Ometria
    email: support@ometria.com
    url: https://ometria.com
servers:
- url: https://api.ometria.com/v2
security:
- apikey: []
tags:
- name: Profiles
paths:
  /profiles/:
    get:
      tags:
      - Profiles
      summary: Fetch list of profiles
      description: Return profiles as a JSON array
      parameters:
      - name: limit
        in: query
        description: The number of records to fetch. Maximum 250.
        required: false
        schema:
          type: integer
          default: 10
      - name: offset
        in: query
        description: Index of first record to fetch
        required: false
        schema:
          type: integer
          default: 0
      - name: updateSince
        in: query
        description: Only return contacts that have been updated since this date.
        schema:
          type: string
          format: date
      - name: updateBefore
        in: query
        description: Only return contacts that have been updated before this date.
        schema:
          type: string
          format: date
      - name: createSince
        in: query
        description: Only return contacts that have been created since this date.
        schema:
          type: string
          format: date
      - name: createBefore
        in: query
        description: Only return contacts that have been created since this date.
        schema:
          type: string
          format: date
      - name: email
        in: query
        description: The email address of the profile to fetch.
        required: false
        schema:
          type: string
      - name: customerId
        in: query
        description: The customer ID of the profile to fetch.
        required: false
        schema:
          type: string
      - name: phoneNumber
        in: query
        description: The phone number of the profile to fetch. Plus signs (+) should be swapped with %2b
        required: false
        schema:
          type: string
      - name: profileHash
        in: query
        description: The profile hash of the profile to fetch.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: List of profile objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Profile'
        '403':
          description: API key is not authorised to access this resource
        '404':
          description: List with specified ID was not found
      operationId: getProfiles
      x-operation-id-source: derived
  /profiles/{profile_id}:
    get:
      tags:
      - Profiles
      summary: Fetch individual profile
      description: Return profile as a JSON object
      parameters:
      - name: profile_id
        in: path
        description: The ID (hash) of the profile to fetch (eg 27f4-8337f0-002384af).
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Return a single profile record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Profile'
        '403':
          description: API key is not authorised to access this resource
        '404':
          description: Profile with specified ID was not found
      operationId: getProfilesByProfileId
      x-operation-id-source: derived
  /merge-profile:
    post:
      tags:
      - Profiles
      summary: Merge profiles based on the provided identifiers
      description: Merge customers_to_merge profiles into the survivor profile. Identifiers supplied here can be any identifier defined in your account's identity resolution configuration (e.g. `customer_id`, `profile_hash`, `email_address`, `phone_number`, or any custom extra identifier such as `loyalty_id`), as well as `profile_id` — the ID (hash) of the profile (e.g. `27f4-8337f0-002384af`).
      requestBody:
        required: true
        description: profiles to merge, customers_to_merge will be merged into survivor
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MergeProfiles'
            example:
              survivor:
                type: email_address
                value: survivor@email.com
              customers_to_merge:
              - type: customer_id
                value: ABC123
              - type: profile_hash
                value: 27f4-26e69b-0000007b
              - type: email_address
                value: customer@email.com
              - type: phone_number
                value: '+447123456789'
              - type: profile_id
                value: 27f4-8337f0-002384af
      responses:
        '202':
          description: Merge profile job placed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: Status of the merge job.
                  job_id:
                    type: integer
                    description: The id of the job that was placed.
              example:
                status: Merge profile job placed
                job_id: 1234
        '400':
          description: Invalid payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
              example:
                status: 400
                type: about:blank
                detail: Cannot merge a profile with itself
                title: Bad Request
        '403':
          description: API key is not authorised to access this resource.
        '404':
          description: Profile not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
              example:
                status: 404
                type: about:blank
                detail: Profile not found
                title: Not Found
        '429':
          description: Max in progress jobs per account reached.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
              example:
                status: 429
                type: about:blank
                detail: Too many merge jobs in progress
                title: Too Many Requests
        '500':
          description: An error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
              example:
                status: 500
                type: about:blank
                detail: Internal Server Error
                title: An error occurred
      operationId: postMergeProfile
      x-operation-id-source: derived
    get:
      tags:
      - Profiles
      summary: Get the status of merge jobs
      description: Get the status of merge jobs.
      parameters:
      - name: limit
        in: query
        description: The limit for pagination purposes.
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
      - name: offset
        in: query
        description: The offset for pagination purposes.
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
      responses:
        '200':
          description: The statuses of the merge jobs.
          content:
            application/json:
              schema:
                type: object
                properties:
                  offset:
                    type: integer
                    description: The offset used for pagination.
                  limit:
                    type: integer
                    description: The limit used for pagination.
                  job_count:
                    type: integer
                    description: The number of merge jobs returned.
                  total_job_count:
                    type: integer
                    description: The total number of merge jobs in the account.
                  jobs:
                    type: array
                    items:
                      $ref: '#/components/schemas/MergeProfileJobStatus'
              example:
                offset: 2
                limit: 10
                job_count: 3
                total_job_count: 5
                jobs:
                - job_id: 12
                  status: finished
                - job_id: 13
                  status: failed
                - job_id: 14
                  status: in_progress
        '400':
          description: Invalid limit or offset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
              example:
                status: 400
                type: about:blank
                detail: -1 is less than the minimum of 0
                title: Bad Request
        '403':
          description: API key is not authorised to access this resource.
        '500':
          description: An error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
              example:
                status: 500
                type: about:blank
                detail: Internal Server Error
                title: An error occurred
      operationId: getMergeProfile
      x-operation-id-source: derived
  /merge-profile/{job_id}:
    get:
      tags:
      - Profiles
      summary: Get the status of a specific merge job
      description: Get the status of a specific merge job.
      parameters:
      - name: job_id
        in: path
        description: The id of the merge job.
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: The statuses of the merge jobs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MergeProfileJobStatus'
              example:
                job_id: 1234
                status: finished
        '403':
          description: API key is not authorised to access this resource.
        '404':
          description: Merge job not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
              example:
                status: 404
                type: about:blank
                detail: Merge job 15 not found
                title: Bad Request
        '500':
          description: An error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
              example:
                status: 500
                type: about:blank
                detail: Internal Server Error
                title: An error occurred
      operationId: getMergeProfileByJobId
      x-operation-id-source: derived
components:
  schemas:
    ProfileStats:
      type: object
      description: Contains numeric stats of a profile.
      properties:
        orders:
          type: number
          description: Number of valid orders this profile has placed.
        orders_attempted:
          type: number
          description: Number of orders attempted by this contact profile (this includes valid as well as invalid orders).
        total_items:
          type: number
          description: Number of items purchased.
        aov:
          type: number
          description: Average order value of this contact profile.
          format: float
        revenue:
          type: number
          description: Total revenue for this contact profile.
          format: float
        visits:
          type: number
          description: Total number of visits for this contact profile.
      example:
        orders: 2
        orders_attempted: 3
        total_items: 5
        aov: 49.72
        revenue: 99.44
        visits: 20
    MergeProfiles:
      type: object
      properties:
        survivor:
          $ref: '#/components/schemas/ProfileIdentifier'
        customers_to_merge:
          type: array
          items:
            $ref: '#/components/schemas/ProfileIdentifier'
          minItems: 1
          maxItems: 5
          uniqueItems: true
    MergeProfileJobStatus:
      type: object
      properties:
        job_id:
          type: integer
          description: The id of the merge job.
        status:
          type: string
          description: The status of the merge job.
          enum:
          - in_progress
          - completed
          - failed
    Profile:
      title: Profile
      type: object
      description: Describes an Ometria contact profile.
      properties:
        '@type':
          type: string
          description: The value must be "profile". This shows that this record is a profile object.
        id:
          type: string
          description: The ID (profile hash) of this profile record, eg 27f4-f0b281-00003039. This is the `profile_hash` accepted by `/field-forget` and `/merge-profile`, and by the `profileHash` parameter of `GET /profiles/`.
        email:
          type: string
          description: The email address of this contact profile.
        name:
          type: string
          description: The name of this contact profile.
        lifecycle_status:
          type: string
          description: The lifecycle status of this contact profile.
          enum:
          - LEAD
          - ACTIVE
          - AT_RISK
          - LAPSED
        seen:
          type: boolean
          description: Whether the contact profile has been seen on your website. Using the identify method in the JS tracker.
        customer_id:
          type: string
          description: The customer ID of this contact profile in your system.
        firstname:
          type: string
          description: The first name of this contact profile.
        middlename:
          type: string
          description: The middle name of this contact profile.
        lastname:
          type: string
          description: The last name of this contact profile.
        prefix:
          type: string
          description: The prefix of this contact profile.
        suffix:
          type: string
          description: The suffix of this contact profile.
        country:
          type: string
          description: The country of this contact profile. Following ISO 3166-1 alpha-2.
          minLength: 2
          maxLength: 2
        country_id:
          type: string
          description: The country of this contact profile. Following ISO 3166-1 alpha-2.
          minLength: 2
          maxLength: 2
          deprecated: true
        gender:
          type: string
          description: The gender for this contact profile.
          enum:
          - m
          - f
          - o
        tags:
          type: array
          description: Custom tags assigned to this profile in the Ometria UI.
          items:
            type: string
        properties:
          description: Custom key / value pairs of this contact profile.
          type: object
        date_of_birth:
          type: string
          description: The date of birth for this contact. Following ISO 8601 date format _YYYY-MM-DD_.
          format: date
        marketing_optin:
          type: boolean
          description: TRUE if this contact has explicitly opted in. FALSE if they have explicitly opted out. NULL otherwise.
        timezone:
          type: string
          description: The timezone of the profile. Values defined in the <a href="https://www.iana.org/time-zones" target="blank">tz database</a>.
        phone_number:
          type: string
          description: The contact's mobile phone number, in E.164/International format (e.g. starting "+447...")
        phone_number_country:
          type: string
          description: The contact's mobile phone number country code, in ISO 3166-1 alpha-2 format (e.g. "GB")
        stats:
          $ref: '#/components/schemas/ProfileStats'
        dates:
          $ref: '#/components/schemas/ProfileDates'
        lists:
          $ref: '#/components/schemas/ProfileLists'
        preferred_lang:
          type: string
          description: 'The preferred language of the contact.

            This is supplied in ISO 639-1 format.'
        identifiers:
          type: array
          description: All identifiers this profile resolves on, including standard identifiers (e.g. `email`, `customer_id`, `phone_number`) and any custom extra identifiers defined in your account's identity resolution configuration (e.g. `loyalty_id`). Each entry has a `type` (the identifier label) and a `value`. See <a href="https://support.ometria.com/hc/en-gb/articles/32595707442077-Custom-identifiers">Custom identifiers</a> for the full format, multi-valued identifiers, and CSV usage.
          items:
            $ref: '#/components/schemas/ProfileIdentifier'
      example:
        '@type': profile
        id: 27f4-f0b281-00003039
        email: bob22@example.com
        name: smith111
        country: null
        seen: false
        customer_id: '55555'
        lastname: smith111
        firstname: null
        middlename: null
        suffix: null
        prefix: null
        gender: m
        tags:
        - Attended VIP event 2017
        properties:
          custom_key: custom value
        date_of_birth: '1984-04-22'
        marketing_optin: null
        stats:
          orders: 1
          orders_attempted: 1
          total_items: 5
          aov: 99.17
          revenue: 99.17
          visits: 20
        dates:
          first_seen: '2014-12-01T05:44:55+00:00'
          last_seen: '2015-02-01T05:44:55+00:00'
          first_purchase: '2015-02-01T05:44:55+00:00'
          last_purchase: '2015-02-01T05:44:55+00:00'
          predicted_next_purchase: '2015-03-01T05:44:55+00:00'
          acquired: '2014-11-07T15:34:35+00:00'
          account_created: '2014-11-07T15:34:35+00:00'
          marketing_optin: '2014-11-09T15:34:35+00:00'
          marketing_optout: null
        preferred_lang: en-GB
        identifiers:
        - type: email
          value: bob22@example.com
        - type: customer_id
          value: '55555'
        - type: loyalty_id
          value: LOY-55555
    ProfileDates:
      type: object
      description: Contains date / time information of a profile
      properties:
        account_created:
          type: string
          description: The date time when this contact was created with given customer_id based on `timestamp_acquired` of the same listing.
          format: date-time
        acquired:
          type: string
          description: The date time when this contact was acquired based on the earliest `timestamp_acquired`.
          format: date-time
        first_seen:
          type: string
          description: The date time when this contact was first seen.
          format: date-time
        last_seen:
          type: string
          description: The date time when this contact was last seen.
          format: date-time
        first_purchase:
          type: string
          description: The date time when this contact first placed an order.
          format: date-time
        last_purchase:
          type: string
          description: The date time when this contact last placed an order.
          format: date-time
        predicted_next_purchase:
          type: string
          description: The date time of the projected next purchase based on the profile's average order gap.
          format: date-time
        marketing_optin:
          type: string
          description: The date time when this contact opted in to receive marketing emails.
          format: date-time
        marketing_optout:
          type: string
          description: The date time when this contact opted out to no longer receive marketing emails.
          format: date-time
      example:
        first_seen: '2014-12-01T05:44:55+00:00'
        last_seen: '2015-02-01T05:44:55+00:00'
        first_purchase: '2015-02-01T05:44:55+00:00'
        last_purchase: '2015-02-01T05:44:55+00:00'
        predicted_next_purchase: '2015-03-01T05:44:55+00:00'
        acquired: '2014-11-07T15:34:35+00:00'
        account_created: '2014-11-07T15:34:35+00:00'
        marketing_optin: '2014-11-09T15:34:35+00:00'
        marketing_optout: null
    ProfileLists:
      type: array
      description: Contains the saved segments (lists) that a profile belongs to.
      items:
        type: object
        properties:
          id:
            type: string
            description: The ID of the list
          title:
            type: string
            description: The title of the list
          type:
            type: string
            enum:
            - STATIC
            - DYNAMIC
      example:
      - id: 123
        title: Title of the list
        type: STATIC
    ProfileIdentifier:
      type: object
      properties:
        type:
          type: string
          description: Type of profile identifier. Any identifier defined in your account's identity resolution configuration is accepted (e.g. `customer_id`, `profile_hash`, `email_address`, `phone_number`, or any custom extra identifier such as `loyalty_id`).
        value:
          type: string
          description: Value of profile identifier.
    ErrorMessage:
      type: object
      properties:
        status:
          type: string
        type:
          type: string
        detail:
          type: string
        title:
          type: string
  securitySchemes:
    apikey:
      type: apiKey
      name: X-Ometria-Auth
      in: header
      description: Ometria API key which can be obtained from your Ometria account administrator
    apiKeyReadTranslations:
      type: apiKey
      name: X-Ometria-Auth
      in: header
      description: 'Ometria API key which can be obtained from your Ometria account administrator. **Note**: The API key must have the scope `read:translations`.'
    apiKeyWriteTranslations:
      type: apiKey
      name: X-Ometria-Auth
      in: header
      description: 'Ometria API key which can be obtained from your Ometria account administrator. **Note**: The API key must have the scope `write:translations`.'
x-explorer-enabled: false
x-readme:
  proxy-enabled: true
  samples-enabled: true