Ometria Contacts API

openapi: 3.2.0
info:
  version: 1.1.0
  title: Ometria data Contacts 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: Contacts
paths:
  /contacts:
    get:
      tags:
      - Contacts
      summary: List Collections
      description: List contact collections along with counts of records in each collection
      parameters: []
      responses:
        '200':
          description: Collection objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ContactCollection'
        '403':
          description: API key is not authorised to access this resource
      operationId: getContacts
      x-operation-id-source: derived
  /contacts/{collection}:
    get:
      tags:
      - Contacts
      summary: List Contacts
      description: List Contacts in Collection with optional filters
      parameters:
      - name: collection
        in: path
        description: The ID of the collection to fetch.
        required: true
        schema:
          type: string
      - name: updateSince
        in: query
        description: 'Only return contacts that have been updated since this date.

          This does not return contacts who have entered or exited a dynamic segment in that time.'
        schema:
          type: string
          format: date
      - name: limit
        in: query
        description: The number of items to return. Maximum 250.
        required: false
        schema:
          type: string
          default: '10'
      - name: offset
        in: query
        description: The index of the first record.
        required: false
        schema:
          type: string
          default: '0'
      responses:
        '200':
          description: List of Contact objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Contact'
        '403':
          description: API key is not authorised to access this resource
      operationId: getContactsByCollection
      x-operation-id-source: derived
  /contacts/{collection}/{contact_id}:
    get:
      tags:
      - Contacts
      summary: Get Contact listing
      description: Return a single Contact record
      parameters:
      - name: collection
        in: path
        description: The ID of the collection to which the contact belongs. The collection acts as a source for the record.
        required: true
        schema:
          type: string
      - name: contact_id
        in: path
        description: The ID of the contact to fetch.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Returns a contact record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '403':
          description: API key is not authorised to access this resource
        '404':
          description: Record with this ID does not exist
      operationId: getContactsByCollectionByContactId
      x-operation-id-source: derived
components:
  schemas:
    ExtraIdentifier:
      title: Extra Identifier
      type: object
      description: An additional identifier for a record, used to attach non-standard customer or record IDs (e.g. loyalty programme IDs, external CRM IDs). Records may carry multiple extra identifiers.
      required:
      - type
      - value
      properties:
        type:
          type: string
          description: The identifier type label. Must contain only lowercase letters and underscores (regex `^[a-z_]+$`), 1-255 characters. Will be coerced to lowercase on ingestion.
          minLength: 1
          maxLength: 255
          pattern: ^[a-z_]+$
          example: loyalty_id
        value:
          type: string
          description: The identifier value (free-form string).
          example: LOY-7898734
      example:
        type: loyalty_id
        value: LOY-7898734
    Contact:
      title: Contact
      type: object
      description: 'Describes an individual Contact listing record. At least one of the following are required to identify the customer: `email`, `customer_id`, `phone_number`, or `extra_identifiers` (any one entry satisfies the requirement). Ometria attempts to merge each contact record into a single profile using the identifiers configured for your account; by default these are `customer_id` and then `email`. Accounts using identity resolution can configure additional identifiers and control how they are matched and merged.'
      required:
      - '@type'
      - id
      properties:
        '@type':
          type: string
          description: The value must be "contact". This shows that this record represents a contact object.
        '@collection':
          type: string
          description: The collection you want the contact to belong to.
        id:
          type: string
          description: 'The ID of this listing within the collection, max length: 255'
        email:
          type: string
          description: 'The contact''s email address, max length: 255, lower case.

            If left empty this field will be set to ''null''.

            You must include either `email` or `customer_id` in every record. Some retailers can also use the `phone_number` or `extra_identifiers` field - speak to your Customer Success Representative if you''re unsure.'
        phone_number:
          type: string
          description: 'The contact''s mobile phone number, in E.164/International format (e.g. starting "+447...") or National format (without the country code prefix, please note that country_id is required in order to validate the phone number in this format).

            You must include either `email` or `customer_id` in every record. Some retailers can also use the `phone_number` or `extra_identifiers` field - speak to your Customer Success Representative if you''re unsure.'
        marketing_optin:
          type: string
          description: The contact's marketing opt-in status.
          enum:
          - EXPLICITLY_OPTEDOUT
          - NOT_SPECIFIED
          - EXPLICITLY_OPTEDIN
        customer_id:
          type: string
          description: 'Your universal customer ID for this contact, if applicable. max length: 255.

            Only use this value if the customer ID is persistent across all your systems (that send data to Ometria).

            You must include either `email` or `customer_id` in every record. Some retailers can also use the `phone_number` or `extra_identifiers` field - speak to your Customer Success Representative if you''re unsure.'
        '@add_to_lists':
          type: array
          description: 'The ID of the segment you want to send this contact to, max length: 16.'
          items:
            type: integer
        '@remove_from_lists':
          type: array
          description: 'The ID of the segment you want to remove this contact from, max length: 16.'
          items:
            type: integer
        '@force_optin':
          type: boolean
          description: If 'True', this field overrides <a href="https://ometria-api-reference.readme.io/docs/contacts-endpoint#marketing-opt-in-rules-of-priority" target="_blank">marketing opt-in priority</a>.
        '@merge':
          type: boolean
          description: If 'True', this call will not override blank fields (i.e. fields that exist but aren't passed)
        prefix:
          type: string
          description: 'The contact''s title.

            Ometria accepts any of the following: Mr, Mrs, Miss, Ms.

            If the gender field is left empty, Ometria infers gender from the prefix (e.g. Mr will be ''m'', Ms will be ''f'', etc.)

            max length: 16.'
        firstname:
          type: string
          description: 'The contact''s first name, max length: 64.'
        middlename:
          type: string
          description: 'The contact''s middle name, max length: 64.'
        lastname:
          type: string
          description: 'The contact''s last name, max length: 64.'
        gender:
          type: string
          description: 'The contact''s gender.

            We currently support the values "m" (man), "f" (woman) and "o" (other).

            Use the value "o" when the contact''s gender is known but it is not "m" or "f". If the contact''s gender is unknown then the field "gender" should not be included.

            If left empty, gender is inferred from the contact''s prefix (e.g ''Ms'' will be ''f'').'
          enum:
          - m
          - f
          - o
        date_of_birth:
          type: string
          description: 'The contact''s date of birth.

            Following ISO 8601 date format YYYY-MM-DD.'
          format: date
        postcode:
          type: string
          description: The contact's postalcode
        city:
          type: string
          description: The contact's city
        country_id:
          type: string
          description: 'The contact''s country, must be 2 characters, upper case, e.g. ''GB''.

            Follow ISO 3166-1 alpha-2.

            If you exceed the character limit this field will pass validation but appear truncated in Ometria.

            If left empty this field will be set to ''null''.'
          minLength: 2
          maxLength: 2
        store_ids:
          type: array
          description: 'An array of strings for which stores the customer belongs to.

            max length: 31, lower case.

            If left empty this field will be set to ''null''.'
          items:
            type: string
        timezone:
          type: string
          description: 'As defined in the <a href="https://www.iana.org/time-zones" target="blank">tz database</a>, max length: 64.'
        properties:
          type: object
          description: Custom key value pairs
        timestamp_acquired:
          type: string
          description: 'The date and time the contact was ''acquired''. Only provide this if known.

            Follow ISO 8601 DateTime format with timezone offset YYYY-MM-DDThh:mm:ss+Z'
          format: date-time
        timestamp_subscribed:
          type: string
          description: 'The date and time the contact was ''subscribed''. Only provide this if known.

            Follow ISO 8601 DateTime format with timezone offset YYYY-MM-DDThh:mm:ss+Z'
          format: date-time
        timestamp_unsubscribed:
          type: string
          description: 'The date and time the contact was ''unsubscribed''. Only provide if known.

            Follow ISO 8601 DateTime format with timezone offset YYYY-MM-DDThh:mm:ss+Z'
          format: date-time
        channels:
          type: object
          description: Contact preferences across different communication channels, e.g. SMS
          properties:
            sms:
              type: object
              description: SMS channel opt-in preferences.
              properties:
                allow_marketing:
                  type: boolean
                  description: Whether the contact is opted in/out for SMS marketing. If left out, this implies unspecified.
                allow_transactional:
                  type: boolean
                  description: Whether the contact is opted in/out to transactional SMS. If left out, it implies 'unspecified'.
                dt_updated_marketing:
                  type: string
                  format: date-time
                  description: 'The date and time the contact updated their marketing SMS preference.

                    Onlyprovide if known.

                    Follow ISO 8601 DateTime format with timezone offset YYYY-MM-DDThh:mm:ss+Z'
                dt_updated_transactional:
                  type: string
                  format: date-time
                  description: 'The date and time the contact updated their transactional SMS preference. Only

                    provide if known.

                    Follow ISO 8601 DateTime format with timezone offset YYYY-MM-DDThh:mm:ss+Z'
        subscriptions:
          type: object
          description: Marketing opt-in preferences for additional channels, e.g. direct mail. Each key is a channel name and its value describes the contact's preference for that channel.
          properties:
            direct_mail:
              type: object
              description: Direct mail (postal) marketing opt-in preference.
              properties:
                allow_marketing:
                  type: boolean
                  description: Whether the contact is opted in/out for direct mail marketing. If left out, this implies unspecified.
                timestamp:
                  type: string
                  format: date-time
                  description: 'The date and time the contact updated their direct mail marketing preference. Only provide if known.

                    Follow ISO 8601 DateTime format with timezone offset YYYY-MM-DDThh:mm:ss+Z'
                value:
                  type: string
                  description: 'The contact''s postal address, supplied as a JSON-encoded string. Supported fields: "address_line_1", "city", "state", "postcode", "country_code" (2 characters, upper case, following ISO 3166-1 alpha-2) and "address_type" (e.g. "shipping").'
        preferred_lang:
          type: string
          description: 'The preferred language of the contact.

            This should be supplied in ISO 639-1 format.'
        extra_identifiers:
          type:
          - array
          - 'null'
          description: Optional list of extra identifiers (such as a loyalty ID) as per your identity resolution configuration, e.g. `loyalty_id`. Custom identifiers must be configured for your account before you send them. 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/ExtraIdentifier'
      example:
        '@type': contact
        '@collection': default
        id: '123'
        email: john.smith@example.com
        phone_number: '+447812123456'
        store_ids:
        - gb
        customer_id: '7898734'
        prefix: Mr
        firstname: John
        middlename: Fredrick
        lastname: Smith
        gender: m
        date_of_birth: '1985-01-05'
        marketing_optin: EXPLICITLY_OPTEDIN
        postcode: SW1A 1AA
        city: London
        country_id: GB
        properties:
          nickname: Johnny
          number_of_cats: 4
        timestamp_subscribed: '2015-01-02T09:00:00+00'
        '@add_to_lists':
        - 1
        - 2
        - 3
        '@remove_from_lists':
        - 4
        - 5
        - 6
        channels:
          sms:
            allow_marketing: true
            allow_transactional: true
            dt_updated_marketing: '2015-01-02T09:00:00+00'
            dt_updated_transactional: '2015-01-02T09:00:00+00'
        subscriptions:
          direct_mail:
            allow_marketing: true
            timestamp: '2015-01-02T09:00:00+00'
            value: '{"address_line_1": "63 Laurelbank Cres", "city": "Keswick", "state": "ON", "postcode": "L4P 4H7", "country_code": "CA", "address_type": "shipping"}'
        preferred_lang: en-GB
        extra_identifiers:
        - type: loyalty_id
          value: LOY-7898734
        - type: external_id
          value: crm-abc-123
    ContactCollection:
      type: object
      description: Describes a collection of Contact listing records.
      properties:
        collection:
          type: string
          description: The collection ID.
        count:
          type: integer
          description: The number of records belonging to the collection.
      example:
        collection: default
        count: 43540
  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