Sinch Contacts API

openapi: 3.2.0
info:
  title: Sinch Conversation Contacts API
  description: The Sinch Conversation API is an omnichannel messaging platform that enables developers to send and receive messages across multiple channels including SMS, RCS, WhatsApp, Facebook Messenger, Instagram, Viber, Telegram, KakaoTalk, and LINE through a single unified API. It provides contact management, conversation tracking, message templating, and webhook callbacks for real-time event handling. The API normalizes message formats across channels, allowing developers to build multichannel messaging experiences without channel-specific integrations.
  version: '1.0'
  contact:
    name: Sinch Support
    url: https://www.sinch.com/contact-us/
  termsOfService: https://www.sinch.com/terms-of-service/
servers:
- url: https://us.conversation.api.sinch.com
  description: US Production Server
- url: https://eu.conversation.api.sinch.com
  description: EU Production Server
- url: https://br.conversation.api.sinch.com
  description: Brazil Production Server
security:
- oAuth2: []
- basicAuth: []
tags:
- name: Contacts
  description: Manage contacts and their channel identities. Contacts group together underlying connected channel recipient identities.
paths:
  /v1/projects/{project_id}/contacts:
    post:
      operationId: createContact
      summary: Create a Contact
      description: Creates a new contact with one or more channel identities.
      tags:
      - Contacts
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateContactRequest'
      responses:
        '200':
          description: Contact created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
    get:
      operationId: listContacts
      summary: List Contacts
      description: Returns a list of contacts in the project with pagination support.
      tags:
      - Contacts
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - name: page_size
        in: query
        description: The number of contacts per page
        schema:
          type: integer
          default: 10
      - name: page_token
        in: query
        description: Pagination token for the next page
        schema:
          type: string
      responses:
        '200':
          description: List of contacts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactList'
        '401':
          description: Unauthorized
  /v1/projects/{project_id}/contacts/{contact_id}:
    get:
      operationId: getContact
      summary: Get a Contact
      description: Returns the details of a specific contact.
      tags:
      - Contacts
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ContactId'
      responses:
        '200':
          description: Contact details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '401':
          description: Unauthorized
        '404':
          description: Contact not found
    patch:
      operationId: updateContact
      summary: Update a Contact
      description: Updates the properties of a specific contact.
      tags:
      - Contacts
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ContactId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateContactRequest'
      responses:
        '200':
          description: Contact updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '401':
          description: Unauthorized
        '404':
          description: Contact not found
    delete:
      operationId: deleteContact
      summary: Delete a Contact
      description: Deletes a specific contact and all associated data.
      tags:
      - Contacts
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ContactId'
      responses:
        '200':
          description: Contact deleted
        '401':
          description: Unauthorized
        '404':
          description: Contact not found
  /v1/projects/{project_id}/contacts:merge:
    post:
      operationId: mergeContacts
      summary: Merge Contacts
      description: Merges two contacts into one, combining their channel identities and conversation history.
      tags:
      - Contacts
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - destination_id
              - source_id
              properties:
                destination_id:
                  type: string
                  description: The contact ID to merge into
                source_id:
                  type: string
                  description: The contact ID to merge from
      responses:
        '200':
          description: Contacts merged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '401':
          description: Unauthorized
components:
  schemas:
    Contact:
      type: object
      properties:
        id:
          type: string
          description: The unique contact identifier
        display_name:
          type: string
          description: The display name of the contact
        email:
          type: string
          format: email
          description: The contact email address
        external_id:
          type: string
          description: An external identifier for the contact
        language:
          type: string
          description: The preferred language of the contact
        metadata:
          type: string
          description: Contact metadata
        channel_identities:
          type: array
          description: The channel identities for the contact
          items:
            $ref: '#/components/schemas/ChannelIdentity'
    ChannelIdentity:
      type: object
      properties:
        channel:
          type: string
          enum:
          - SMS
          - RCS
          - WHATSAPP
          - MESSENGER
          - INSTAGRAM
          - VIBER
          - VIBERBM
          - TELEGRAM
          - KAKAOTALK
          - LINE
          - MMS
          description: The channel type
        identity:
          type: string
          description: The channel-specific identity
        app_id:
          type: string
          description: The app ID for the channel
    UpdateContactRequest:
      type: object
      properties:
        display_name:
          type: string
          description: Updated display name
        email:
          type: string
          format: email
          description: Updated email address
        external_id:
          type: string
          description: Updated external identifier
        language:
          type: string
          description: Updated preferred language
        metadata:
          type: string
          description: Updated metadata
        channel_identities:
          type: array
          description: Updated channel identities
          items:
            $ref: '#/components/schemas/ChannelIdentity'
    ContactList:
      type: object
      properties:
        contacts:
          type: array
          description: List of contacts
          items:
            $ref: '#/components/schemas/Contact'
        next_page_token:
          type: string
          description: Pagination token for the next page
    CreateContactRequest:
      type: object
      required:
      - channel_identities
      properties:
        display_name:
          type: string
          description: The display name
        email:
          type: string
          format: email
          description: The email address
        external_id:
          type: string
          description: An external identifier
        language:
          type: string
          description: The preferred language
        metadata:
          type: string
          description: Contact metadata
        channel_identities:
          type: array
          description: Channel identities
          items:
            $ref: '#/components/schemas/ChannelIdentity'
  parameters:
    ProjectId:
      name: project_id
      in: path
      required: true
      description: The unique project identifier
      schema:
        type: string
    ContactId:
      name: contact_id
      in: path
      required: true
      description: The unique contact identifier
      schema:
        type: string
  securitySchemes:
    oAuth2:
      type: oauth2
      description: OAuth 2.0 client credentials flow using project key ID and secret.
      flows:
        clientCredentials:
          tokenUrl: https://auth.sinch.com/oauth2/token
          scopes: {}
    basicAuth:
      type: http
      scheme: basic
      description: Key ID as username and key secret as password.
externalDocs:
  description: Sinch Conversation API Documentation
  url: https://developers.sinch.com/docs/conversation