Omnisend Contacts API

openapi: 3.0.0
info:
  contact: {}
  description: Manage contacts.
  title: Contacts API
  version: '2026'
  x-api-evangelist:
    harvested: '2026-08-13'
    method: searched
    source: https://dash.readme.com/api/v1/api-registry/ecnnswezmscxw9nj
    source-note: Published by Omnisend on its own docs host api-docs.omnisend.com (ReadMe project @omnisend,
      branch v2026-03-15); registry document referenced by the reference page as oasPublicUrl.
paths:
  /contacts:
    get:
      description: 'Returns a paginated list of contacts filtered by the provided query parameters.


        **Scopes:**

        `contacts.read`


        **Rate Limiting:**

        This endpoint is rate limited to 400 requests per minute.


        **Filter restrictions:**

        - `tag` and `status` cannot be used together in the same request.

        - `updatedAtFrom` cannot be combined with `email`, `phone`, `status`, `segmentID`, or `tag`.

        '
      parameters:
      - description: 'Number of items per page. Range: 1-250. Default: 100'
        in: query
        name: limit
        schema:
          type: integer
          minimum: 1
          maximum: 250
      - description: Opaque cursor for fetching the next page (from paging.cursors.after)
        in: query
        name: after
        schema:
          type: string
      - description: Opaque cursor for fetching the previous page (from paging.cursors.before)
        in: query
        name: before
        schema:
          type: string
      - description: 'Sort field. Default: createdAt'
        in: query
        name: sort
        schema:
          type: string
          enum:
          - createdAt
          - updatedAt
      - description: 'Sort direction. Default: desc'
        in: query
        name: direction
        schema:
          type: string
          enum:
          - asc
          - desc
      - description: Filter by email address
        in: query
        name: email
        schema:
          type: string
      - description: Filter by phone number
        in: query
        name: phone
        schema:
          type: string
      - description: Contact subscription status filter. Cannot be combined with tag
        in: query
        name: status
        schema:
          type: string
          enum:
          - subscribed
          - unsubscribed
          - nonSubscribed
      - description: Filter by segment ID
        in: query
        name: segmentID
        schema:
          type: string
      - description: Filter by tag. Cannot be combined with status
        in: query
        name: tag
        schema:
          type: string
      - description: Filter contacts updated at or after this RFC3339 timestamp. Cannot be combined with
          email, phone, status, segmentID, or tag
        in: query
        name: updatedAtFrom
        schema:
          type: string
      - $ref: '#/components/parameters/APIVersionHeader'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListContactsResponse'
        '400':
          description: Request contains invalid or missing fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblem'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Insufficient permissions for this operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '410':
          description: API version has been retired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitProblem'
        '500':
          description: Unexpected error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - Bearer:
        - contacts.read
      - ApiKeyAuth: []
      summary: List contacts
      tags:
      - Contacts
    patch:
      description: 'Updates the contact matching the provided email address.


        **Scopes:**

        `contacts.write`


        **Rate Limiting:**

        This endpoint is rate limited to 400 requests per minute.'
      parameters:
      - description: Contact email address
        in: query
        name: email
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/APIVersionHeader'
      requestBody:
        $ref: '#/components/requestBodies/ContactRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactResponse'
        '400':
          description: Request contains invalid or missing fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblem'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Insufficient permissions for this operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: Contact not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '409':
          description: Contact identifier already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '410':
          description: API version has been retired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitProblem'
        '500':
          description: Unexpected error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - Bearer:
        - contacts.write
      - ApiKeyAuth: []
      summary: Update contact by email
      tags:
      - Contacts
    post:
      description: 'Creates a new contact. If a contact with the provided email identifier already exists,
        it will be updated instead.

        Returns `201 Created` for new contacts and `200 OK` when an existing contact was updated.


        **Scopes:**

        `contacts.write`


        **Rate Limiting:**

        This endpoint is rate limited to 400 requests per minute.'
      parameters:
      - $ref: '#/components/parameters/APIVersionHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactRequest'
        description: Contact to create or update
        required: true
      responses:
        '200':
          description: Existing contact updated (upsert by email)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactResponse'
        '201':
          description: Contact created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactResponse'
        '400':
          description: Request contains invalid or missing fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblem'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Insufficient permissions for this operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '410':
          description: API version has been retired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitProblem'
        '500':
          description: Unexpected error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - Bearer:
        - contacts.write
      - ApiKeyAuth: []
      summary: Create or update existing contact
      tags:
      - Contacts
  /contacts/{id}:
    get:
      description: 'Returns the contact with the specified ID.


        **Scopes:**

        `contacts.read`


        **Rate Limiting:**

        This endpoint is rate limited to 400 requests per minute.'
      parameters:
      - description: Contact ID
        in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/APIVersionHeader'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactResponse'
        '400':
          description: Request contains invalid or missing fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblem'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Insufficient permissions for this operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: Contact not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '410':
          description: API version has been retired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitProblem'
        '500':
          description: Unexpected error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - Bearer:
        - contacts.read
      - ApiKeyAuth: []
      summary: Get contact
      tags:
      - Contacts
    patch:
      description: 'Updates the contact with the specified ID.


        **Scopes:**

        `contacts.write`


        **Rate Limiting:**

        This endpoint is rate limited to 400 requests per minute.'
      parameters:
      - description: Contact ID
        in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/APIVersionHeader'
      requestBody:
        $ref: '#/components/requestBodies/ContactRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactResponse'
        '400':
          description: Request contains invalid or missing fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblem'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Insufficient permissions for this operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: Contact not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '409':
          description: Contact identifier already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '410':
          description: API version has been retired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitProblem'
        '500':
          description: Unexpected error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - Bearer:
        - contacts.write
      - ApiKeyAuth: []
      summary: Update contact by ID
      tags:
      - Contacts
  /contacts/tags:
    delete:
      description: 'Removes the specified tags from contacts selected by contact IDs, emails, phone numbers
        or a segment.

        At least one of `contactIDs`, `emails`, `phones` or `segmentID` is required.

        Selectors can be combined and are applied additively — the tags are removed from the union of
        all

        matched contacts: every contact in `contactIDs`, every contact matched by an address in `emails`,

        every contact matched by a number in `phones` and every member of `segmentID`. A contact matched
        by

        more than one selector is processed once. Emails and phones with no matching contact are silently
        ignored.

        Untagging is performed asynchronously, so the tags may not disappear immediately.


        **Scopes:**

        `contacts.write`


        **Rate Limiting:**

        This endpoint is rate limited to 60 requests per minute.'
      parameters:
      - $ref: '#/components/parameters/APIVersionHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RemoveTagsRequest'
        description: Contact selectors and tags to remove
        required: true
      responses:
        '202':
          description: Untagging accepted
        '400':
          description: Request contains invalid or missing fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblem'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Insufficient permissions for this operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '410':
          description: API version has been retired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitProblem'
        '500':
          description: Unexpected error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - Bearer:
        - contacts.write
      - ApiKeyAuth: []
      summary: Batch remove tags
      tags:
      - Contacts
    post:
      description: 'Adds the specified tags to contacts selected by contact IDs, emails, phone numbers
        or a segment.

        At least one of `contactIDs`, `emails`, `phones` or `segmentID` is required.

        Selectors can be combined and are applied additively — the union of all matched contacts is tagged:

        every contact in `contactIDs`, every contact matched by an address in `emails`, every contact
        matched

        by a number in `phones` and every member of `segmentID`. A contact matched by more than one selector

        is tagged once. Emails and phones with no matching contact are silently ignored.

        Tagging is performed asynchronously, so the tags may not be visible immediately.


        **Scopes:**

        `contacts.write`


        **Rate Limiting:**

        This endpoint is rate limited to 60 requests per minute.'
      parameters:
      - $ref: '#/components/parameters/APIVersionHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddTagsRequest'
        description: Contact selectors and tags to add
        required: true
      responses:
        '202':
          description: Tagging accepted
        '400':
          description: Request contains invalid or missing fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblem'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Insufficient permissions for this operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '410':
          description: API version has been retired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitProblem'
        '500':
          description: Unexpected error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - Bearer:
        - contacts.write
      - ApiKeyAuth: []
      summary: Batch add tags
      tags:
      - Contacts
servers:
- url: https://api.omnisend.com/api
components:
  parameters:
    APIVersionHeader:
      description: API version that specifies the response format and behaviour
      in: header
      name: Omnisend-Version
      required: true
      schema:
        type: string
        default: '2026-03-15'
  requestBodies:
    ContactRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ContactRequest'
      description: Contact fields to update
      required: true
  securitySchemes:
    ApiKeyAuth:
      description: 'API Key authentication. Value format: ''Omnisend-API-Key {api-key}'''
      in: header
      name: Authorization
      type: apiKey
      x-default: Omnisend-API-Key your-api-key
    Bearer:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://app.omnisend.com/oauth2/token
          scopes:
            contacts.read: Read contacts
            contacts.write: Create, update and delete contacts
  schemas:
    AddTagsRequest:
      description: Payload for batch adding tags to contacts.
      properties:
        contactIDs:
          description: Contact IDs to add tags to
          example:
          - 60a6170920d91c215e949b5c
          items:
            type: string
          maxItems: 250
          type: array
        emails:
          description: Emails of contacts to add tags to
          example:
          - contact@omnisend.com
          items:
            type: string
          maxItems: 250
          type: array
        phones:
          description: Phone numbers of contacts to add tags to, in E.164 format
          example:
          - '+1234567890'
          items:
            type: string
          maxItems: 250
          type: array
        segmentID:
          description: Segment ID whose contacts get the tags
          example: 60a6170920d91c215e949b5c
          type: string
        tags:
          description: Tags to add
          example:
          - tag1
          - tag2
          items:
            type: string
          maxItems: 100
          minItems: 1
          type: array
      required:
      - tags
      type: object
    Channel:
      description: Channel subscription status.
      properties:
        status:
          description: Channel subscription status
          enum:
          - subscribed
          - unsubscribed
          - nonSubscribed
          example: subscribed
          type: string
        statusChangedAt:
          description: Timestamp when the channel status last changed
          example: '2023-05-22T10:25:14.263Z'
          type: string
      type: object
    Consent:
      description: Consent record for a contact channel.
      properties:
        channel:
          description: Channel type this consent applies to
          enum:
          - email
          - sms
          example: email
          type: string
        createdAt:
          description: Consent collection timestamp
          example: '2021-05-20T12:00:00Z'
          type: string
        ip:
          description: IP address from which consent was collected
          example: 161.1.1.1
          type: string
        source:
          description: Source through which consent was obtained (e.g. omnisend-form, api)
          example: api
          type: string
        userAgent:
          description: User agent string from the consent collection request
          example: Mozilla/5.0
          type: string
      type: object
    ContactChannelRequest:
      description: Channel subscription details.
      properties:
        status:
          description: Subscription status
          enum:
          - subscribed
          - nonSubscribed
          - unsubscribed
          example: subscribed
          type: string
        statusChangedAt:
          description: Date when the channel status was last changed
          example: '2024-01-01T00:00:00Z'
          type: string
      required:
      - status
      type: object
    ContactConsentRequest:
      description: Consent record.
      properties:
        createdAt:
          description: Consent collection timestamp in RFC3339 format. Defaults to current time if not
            provided
          example: '2026-01-01T00:00:00Z'
          type: string
        ip:
          description: IP address at time of consent
          example: 192.168.1.1
          type: string
        source:
          description: Source of consent
          example: omnisend-form
          type: string
        userAgent:
          description: User agent at time of consent
          example: Mozilla/5.0
          type: string
      type: object
    ContactIdentifierRequest:
      description: 'A unique contact identifier (email or phone). For phone: provide the full number with
        country code prefix in E.164 format (e.g. +1234567890).'
      properties:
        channels:
          additionalProperties:
            $ref: '#/components/schemas/ContactChannelRequest'
          description: Communication channels for this identifier
          type: object
        consent:
          allOf:
          - $ref: '#/components/schemas/ContactConsentRequest'
          description: Consent information
        id:
          description: 'Identifier value. For email: a valid email address. For phone: full phone number
            in E.164 format with country code prefix (e.g. +1234567890)'
          example: example@example.com
          type: string
        sendWelcomeMessage:
          description: Whether to send a welcome message for this identifier. Defaults to true. Takes
            effect only if the welcome workflow is enabled.
          example: true
          type: boolean
        source:
          description: Source of the identifier
          example: api
          type: string
        type:
          description: Identifier type
          enum:
          - email
          - phone
          example: email
          type: string
      required:
      - id
      - type
      type: object
    ContactRequest:
      description: Payload for creating or updating a contact.
      properties:
        address:
          description: Street, house number, apartment number.
          example: 1234 Main St
          type: string
        birthdate:
          description: Contact birthdate in YYYY-MM-DD format
          example: '1990-01-01'
          type: string
        city:
          description: City
          example: Los Angeles
          type: string
        country:
          description: Country name. Used to derive ISO country code when countryCode is not provided
          example: United States
          type: string
        countryCode:
          description: ISO 3166-1 alpha-2 country code. Takes priority over country when both are provided
          example: US
          type: string
        createdAt:
          description: Contact creation timestamp. If provided, stored as "externalCreated" custom property
          example: '2024-01-01T00:00:00Z'
          type: string
        customProperties:
          additionalProperties: true
          description: You can add your own custom properties. Read more in https://api-docs.omnisend.com/reference/contacts#custom-properties
          type: object
        firstName:
          description: Contact first name
          example: John
          type: string
        gender:
          description: Contact gender. m - male, f - female
          enum:
          - m
          - f
          example: m
          type: string
        identifiers:
          description: Contact identifiers (email and/or phone)
          items:
            $ref: '#/components/schemas/ContactIdentifierRequest'
          type: array
        lastName:
          description: Contact last name
          example: Doe
          type: string
        postalCode:
          description: Postal or zip code
          example: '90001'
          type: string
        state:
          description: State or region
          example: New York
          type: string
        tags:
          description: 'Labels assigned to the contact. When creating a contact, it is strongly advised
            to include a source tag, e.g. "source: shopify".'
          example:
          - tag1
          - tag2
          items:
            type: string
          maxItems: 100
          type: array
      type: object
    ContactResponse:
      description: Contact resource representation.
      properties:
        address:
          description: Contact Street, house number, apartment number
          example: 1234 Main St
          type: string
        birthdate:
          description: Contact birthdate in YYYY-MM-DD format
          example: '1990-01-01'
          type: string
        city:
          description: Contact city
          example: Los Angeles
          type: string
        consents:
          description: Consent records per channel, sorted by collection date (read-only)
          items:
            $ref: '#/components/schemas/Consent'
          readOnly: true
          type: array
        country:
          description: Contact country name
          example: United States
          type: string
        countryCode:
          description: ISO 3166-1 alpha-2 country code
          example: US
          type: string
        createdAt:
          description: Contact creation timestamp (read-only)
          example: '2021-05-20T12:00:00Z'
          readOnly: true
          type: string
        customProperties:
          additionalProperties: true
          description: Custom contact properties defined for the brand
          type: object
        email:
          description: Primary email address derived from the email identifier (read-only)
          example: example@example.com
          readOnly: true
          type: string
        firstName:
          description: Contact first name
          example: John
          type: string
        gender:
          description: Contact gender
          enum:
          - m
          - f
          example: m
          type: string
        id:
          description: Contact unique identifier (read-only)
          example: 60a6170920d91c215e949b5c
          readOnly: true
          type: string
        identifiers:
          description: Contact identifiers with channel subscription details
          items:
            $ref: '#/components/schemas/Identifier'
          type: array
        lastName:
          description: Contact last name
          example: Doe
          type: string
        optIns:
          description: Opt-in history per channel, sorted by date (read-only)
          items:
            $ref: '#/components/schemas/OptIn'
          readOnly: true
          type: array
        phone:
          description: Phone numbers derived from phone identifiers (read-only)
          example:
          - '+1234567890'
          items:
            type: string
          readOnly: true
          type: array
        postalCode:
          description: Contact postal or ZIP code
          example: '90001'
          type: string
        segments:
          description: IDs of segments the contact belongs to (read-only)
          items:
            type: string
          readOnly: true
          type: array
        state:
          description: State or province name
          example: New York
          type: string
        status:
          description: Email channel subscription status derived from the primary email identifier (read-only)
          enum:
          - subscribed
          - unsubscribed
          - nonSubscribed
          example: subscribed
          readOnly: true
          type: string
        statuses:
          description: Most recent subscription status per channel, sorted by date (read-only)
          items:
            $ref: '#/components/schemas/ContactStatus'
          readOnly: true
          type: array
        tags:
          description: Labels assigned to the contact
          example:
          - tag1
          - tag2
          - tag3
          items:
            type: string
          type: array
        updatedAt:
          description: Contact last updated timestamp (read-only)
          example: '2021-05-20T12:30:00Z'
          readOnly: true
          type: string
      type: object
    ContactStatus:
      description: Contact status per channel.
      properties:
        channel:
          description: Channel type
          enum:
          - email
          - sms
          example: email
          type: string
        status:
          description: Channel subscription status
          enum:
          - subscribed
          - unsubscribed
          - nonSubscribed
          example: subscribed
          type: string
        statusChangedAt:
          description: Timestamp when the status last changed
          example: '2021-05-20T12:00:00Z'
          type: string
      type: object
    CursorsResponse:
      description: Cursor pointers for paginating forward and backward through results
      properties:
        after:
          description: Opaque cursor for fetching the next page of results
          example: eyJpZCI6ImNhbXAtNDU2In0
          type: string
          nullable: true
        before:
          description: Opaque cursor for fetching the previous page of results
          example: eyJpZCI6ImNhbXAtMTIzIn0
          type: string
          nullable: true
      type: object
    FieldError:
      description: A single field validation failure within a validation error response.
      properties:
        code:
          description: Error code indicating the type o

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