openapi: 3.0.1
info:
  title: Respond.io Developer Comments Contacts API
  description: REST API for the respond.io omnichannel customer-conversation management platform. Manage contacts, send and read messages across connected channels, open and close conversations, assign users, post internal comments, manage tags and custom fields, and configure webhooks. Requests and responses are JSON. Contacts are addressed by an identifier of the form `id:{id}`, `email:{email}`, or `phone:{phone}`.
  termsOfService: https://respond.io/terms-and-conditions
  contact:
    name: Respond.io Support
    url: https://developers.respond.io/
  version: '2.0'
servers:
- url: https://api.respond.io/v2
security:
- bearerAuth: []
tags:
- name: Contacts
  description: Create, read, update, merge, list, and delete contacts.
paths:
  /contact:
    post:
      operationId: createContact
      tags:
      - Contacts
      summary: Create a contact
      description: Creates a new contact in the workspace.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactCreate'
      responses:
        '200':
          description: Contact created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '429':
          $ref: '#/components/responses/RateLimited'
  /contact/create_or_update/{identifier}:
    post:
      operationId: createOrUpdateContact
      tags:
      - Contacts
      summary: Create or update a contact
      description: Creates a contact if none matches the identifier, otherwise updates the existing contact.
      parameters:
      - $ref: '#/components/parameters/Identifier'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactCreate'
      responses:
        '200':
          description: Contact created or updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '429':
          $ref: '#/components/responses/RateLimited'
  /contact/list:
    get:
      operationId: listContacts
      tags:
      - Contacts
      summary: List contacts
      description: Returns a paginated list of contacts in the workspace.
      parameters:
      - name: cursorId
        in: query
        description: Cursor id for pagination.
        required: false
        schema:
          type: integer
      - name: limit
        in: query
        description: Number of records to return (max 100).
        required: false
        schema:
          type: integer
          default: 10
      responses:
        '200':
          description: A list of contacts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Contact'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '429':
          $ref: '#/components/responses/RateLimited'
  /contact/{identifier}:
    get:
      operationId: getContact
      tags:
      - Contacts
      summary: Get a contact
      description: Retrieves a single contact by identifier.
      parameters:
      - $ref: '#/components/parameters/Identifier'
      responses:
        '200':
          description: The contact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
    put:
      operationId: updateContact
      tags:
      - Contacts
      summary: Update a contact
      description: Updates the fields of an existing contact.
      parameters:
      - $ref: '#/components/parameters/Identifier'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactCreate'
      responses:
        '200':
          description: Contact updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
    delete:
      operationId: deleteContact
      tags:
      - Contacts
      summary: Delete a contact
      description: Permanently deletes a contact from the workspace.
      parameters:
      - $ref: '#/components/parameters/Identifier'
      responses:
        '200':
          description: Contact deleted.
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /contact/merge:
    post:
      operationId: mergeContacts
      tags:
      - Contacts
      summary: Merge contacts
      description: Merges a secondary contact into a primary contact, consolidating conversations, tags, and fields onto the primary.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - primaryContactId
              - secondaryContactId
              properties:
                primaryContactId:
                  type: integer
                  description: Id of the contact to keep.
                secondaryContactId:
                  type: integer
                  description: Id of the contact merged into the primary.
      responses:
        '200':
          description: Contacts merged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '429':
          $ref: '#/components/responses/RateLimited'
  /contact/{identifier}/channel:
    get:
      operationId: listContactChannels
      tags:
      - Contacts
      summary: List a contact's channels
      description: Lists the messaging channels a contact is reachable on.
      parameters:
      - $ref: '#/components/parameters/Identifier'
      responses:
        '200':
          description: A list of channels.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Channel'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  parameters:
    Identifier:
      name: identifier
      in: path
      required: true
      description: Contact identifier in the form id:{id}, email:{email}, or phone:{phone}.
      schema:
        type: string
      example: phone:+60123456789
  schemas:
    Contact:
      type: object
      properties:
        id:
          type: integer
          description: System-assigned contact id.
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
        language:
          type: string
        profilePic:
          type: string
          format: uri
        countryCode:
          type: string
        status:
          type: string
          description: Lifecycle stage of the contact.
        assignee:
          type: string
          nullable: true
        created:
          type: integer
          description: Unix timestamp when the contact was created.
        tags:
          type: array
          items:
            type: string
        customFields:
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldValue'
    CustomFieldValue:
      type: object
      properties:
        name:
          type: string
        value:
          type: string
    ContactCreate:
      type: object
      properties:
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
        language:
          type: string
        profilePic:
          type: string
          format: uri
        countryCode:
          type: string
        customFields:
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldValue'
    Channel:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        source:
          type: string
          description: Channel source such as whatsapp, messenger, telegram, email, sms.
        meta:
          type: object
          additionalProperties: true
    Pagination:
      type: object
      properties:
        cursorId:
          type: integer
          nullable: true
        hasMore:
          type: boolean
    Error:
      type: object
      properties:
        message:
          type: string
        status:
          type: integer
  responses:
    RateLimited:
      description: Too many requests. Limited to 5 requests per second per method.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API Access Token from Settings > Integrations > Developer API, sent in the Authorization header as `Bearer {token}`.