Podium Contact API

openapi: 3.2.0
info:
  title: Contacts Contact API
  version: 2021.04.01
servers:
- url: https://api.podium.com
  variables: {}
security: []
tags:
- name: Contact
paths:
  /v4/contacts:
    get:
      callbacks: {}
      description: 'List all contacts.


        Required scope: `read_contacts`.'
      operationId: contact.index
      parameters:
      - description: Retrieves the page of items that comes after the `cursor`.
        in: query
        name: cursor
        required: false
        schema:
          description: Cursor used to access next or previous page in pagination.
          example: MDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAw
          type: string
      - description: Max number of items to return per request. Defaults to `10`.
        in: query
        name: limit
        required: false
        schema:
          default: 10
          example: 10
          maximum: 100
          minimum: 0
          type: integer
      - description: 'Filter contacts by updated_at. It will retrieve contacts updated after the provided date. Format: `YYYY-MM-DDTHH:MM:SSZ`'
        in: query
        name: updated_at
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/contact'
                  metadata:
                    description: Additional response data.
                    properties:
                      url:
                        description: The resource URL.
                        example: https://www.podium.com/
                        type: string
                    type: object
                type: object
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                properties:
                  code:
                    description: Podium code for the error.
                    type: integer
                  message:
                    description: Specific details about the error.
                    type:
                    - string
                    - 'null'
                  moreInfo:
                    description: URL providing more information about the error.
                    type: string
                title: Error
                type: object
          description: Error response.
      summary: List all contacts
      tags:
      - Contact
    post:
      callbacks: {}
      description: 'Create a contact. If a contact with the same phone number, email, or conversation uid is found it will update the contact.


        Required scope: `write_contacts`.

        '
      operationId: contact.create
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                address:
                  description: The address of the resource
                  properties:
                    addressLine1:
                      description: The first line of the address
                      example: 123 Main St
                      type:
                      - string
                      - 'null'
                    addressLine2:
                      description: The second line of the address
                      example: Apt 101
                      type:
                      - string
                      - 'null'
                    city:
                      description: The city of the address
                      example: Lehi
                      type:
                      - string
                      - 'null'
                    country:
                      description: The country of the address
                      example: US
                      type:
                      - string
                      - 'null'
                    postalCode:
                      description: The postal code of the address
                      example: '84043'
                      type:
                      - string
                      - 'null'
                    state:
                      description: The state of the address
                      example: UT
                      type:
                      - string
                      - 'null'
                  type:
                  - object
                  - 'null'
                attributes:
                  description: List of attribute objects
                  items:
                    description: An attribute contact
                    properties:
                      uid:
                        description: Podium unique identifier for attribute.
                        example: 00000000-0000-0000-0000-000000000000
                        format: uuid
                        type: string
                      value:
                        description: The value of the attribute
                        example: Brown eyes
                        type: string
                    type: object
                  type: array
                contactStatus:
                  description: A contact status, you need either the name or uid
                  properties:
                    name:
                      description: The status of the contact
                      example: Prospect
                      type: string
                    uid:
                      description: Podium unique identifier for contact status.
                      example: 00000000-0000-0000-0000-000000000000
                      format: uuid
                      type: string
                  type: object
                email:
                  description: The email address of the resource
                  example: john.doe@podium.com
                  pattern: (.+)@(.+)\.(.+)
                  type: string
                locations:
                  description: List of location UIDs
                  items:
                    description: Podium unique identifier for location.
                    example: 00000000-0000-0000-0000-000000000000
                    format: uuid
                    type: string
                  type: array
                name:
                  description: The name of the resource
                  example: John Doe
                  type: string
                phoneNumber:
                  description: The phone number of the resource
                  example: '+18884441234'
                  pattern: ^\+[1-9]\d{1,15}$
                  type: string
                tags:
                  description: List of tag UIDs
                  items:
                    description: Podium unique identifier for tag.
                    example: 00000000-0000-0000-0000-000000000000
                    format: uuid
                    type: string
                  type: array
              required:
              - locations
              - name
              type: object
        description: Create contact params
        required: true
      responses:
        '202':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/contact_upsert'
                  metadata:
                    description: Additional response data.
                    properties:
                      url:
                        description: The resource URL.
                        example: https://www.podium.com/
                        type: string
                    type: object
                type: object
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                properties:
                  code:
                    description: Podium code for the error.
                    type: integer
                  message:
                    description: Specific details about the error.
                    type:
                    - string
                    - 'null'
                  moreInfo:
                    description: URL providing more information about the error.
                    type: string
                title: Error
                type: object
          description: Error response.
      summary: Create a contact
      tags:
      - Contact
  /v4/contacts/campaigns/opt_in:
    post:
      callbacks: {}
      description: "Opt in a contact into receiving campaign messages.\n         Note: this endpoint requires your application to be whitelisted.\n          Please contact our support team to get your application whitelisted.\n\nRequired scope: write_contacts"
      operationId: contact.opt_in
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              properties:
                channel:
                  properties:
                    identifier:
                      description: Identifier of the communication channel
                      example: '+15555555555'
                      type: string
                    type:
                      description: Type of communication channel
                      enum:
                      - PHONE
                      type: string
                  required:
                  - identifier
                  - type
                  type: object
                locationUid:
                  description: Podium unique identifier for the location opted in from
                  example: 00000000-0000-0000-0000-000000000000
                  format: uuid
                  type: string
                name:
                  description: Contacts name
                  type: string
                tags:
                  description: Campaign tags.
                  items:
                    type: string
                  type: array
              required:
              - channel
              - locationUid
              type: object
        description: Contact campaign opt in params
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/contact'
                  metadata:
                    description: Additional response data.
                    properties:
                      url:
                        description: The resource URL.
                        example: https://www.podium.com/
                        type: string
                    type: object
                type: object
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                properties:
                  code:
                    description: Podium code for the error.
                    type: integer
                  message:
                    description: Specific details about the error.
                    type:
                    - string
                    - 'null'
                  moreInfo:
                    description: URL providing more information about the error.
                    type: string
                title: Error
                type: object
          description: Error response.
      summary: Opt in a contact
      tags:
      - Contact
  /v4/contacts/campaigns/opt_out:
    post:
      callbacks: {}
      description: "Opt out a contact from receiving campaign messages.\n         Note: this endpoint requires your application to be whitelisted.\n          Please contact our support team to get your application whitelisted.\n\nRequired scope: write_contacts"
      operationId: contact.opt_out
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              properties:
                channel:
                  properties:
                    identifier:
                      description: Identifier of the communication channel
                      example: '+15555555555'
                      type: string
                    type:
                      description: Type of communication channel
                      enum:
                      - PHONE
                      type: string
                  required:
                  - identifier
                  - type
                  type: object
              required:
              - channel
              type: object
        description: Contact campaign opt out params
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/contact'
                  metadata:
                    description: Additional response data.
                    properties:
                      url:
                        description: The resource URL.
                        example: https://www.podium.com/
                        type: string
                    type: object
                type: object
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                properties:
                  code:
                    description: Podium code for the error.
                    type: integer
                  message:
                    description: Specific details about the error.
                    type:
                    - string
                    - 'null'
                  moreInfo:
                    description: URL providing more information about the error.
                    type: string
                title: Error
                type: object
          description: Error response.
      summary: Opt out a contact
      tags:
      - Contact
  /v4/contacts/{identifier}:
    delete:
      callbacks: {}
      description: 'Delete a contact with a conversation uid, email, or phone number.


        Required scope: `write_contacts`.'
      operationId: contact.delete
      parameters:
      - description: Conversation uid, phone number, or email to identify the contact. Phone number should be formatted as '+15555555555'
        in: path
        name: identifier
        required: true
        schema:
          type: string
      responses:
        '202':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/contact_upsert'
                  metadata:
                    description: Additional response data.
                    properties:
                      url:
                        description: The resource URL.
                        example: https://www.podium.com/
                        type: string
                    type: object
                type: object
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                properties:
                  code:
                    description: Podium code for the error.
                    type: integer
                  message:
                    description: Specific details about the error.
                    type:
                    - string
                    - 'null'
                  moreInfo:
                    description: URL providing more information about the error.
                    type: string
                title: Error
                type: object
          description: Error response.
      summary: Delete a contact
      tags:
      - Contact
    get:
      callbacks: {}
      description: 'Get a contact with a conversation uid, email, or phone number.


        Required scope: `read_contacts`.'
      operationId: contact.get
      parameters:
      - description: Conversation uid, phone number, or email to identify the contact. Phone number should be formatted as '+15555555555'
        in: path
        name: identifier
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/contact'
                  metadata:
                    description: Additional response data.
                    properties:
                      url:
                        description: The resource URL.
                        example: https://www.podium.com/
                        type: string
                    type: object
                type: object
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                properties:
                  code:
                    description: Podium code for the error.
                    type: integer
                  message:
                    description: Specific details about the error.
                    type:
                    - string
                    - 'null'
                  moreInfo:
                    description: URL providing more information about the error.
                    type: string
                title: Error
                type: object
          description: Error response.
      summary: Retrieve a contact
      tags:
      - Contact
    patch:
      callbacks: {}
      description: 'Update a contact with using a conversation uid, email, or phone number as an identifier.


        Required scope: `write_contacts`.'
      operationId: contact.update
      parameters:
      - description: Conversation uid, phone number, or email to identify the contact. Phone number should be formatted as '+15555555555'
        in: path
        name: identifier
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              minProperties: 1
              properties:
                address:
                  description: The address of the resource
                  properties:
                    addressLine1:
                      description: The first line of the address
                      example: 123 Main St
                      type:
                      - string
                      - 'null'
                    addressLine2:
                      description: The second line of the address
                      example: Apt 101
                      type:
                      - string
                      - 'null'
                    city:
                      description: The city of the address
                      example: Lehi
                      type:
                      - string
                      - 'null'
                    country:
                      description: The country of the address
                      example: US
                      type:
                      - string
                      - 'null'
                    postalCode:
                      description: The postal code of the address
                      example: '84043'
                      type:
                      - string
                      - 'null'
                    state:
                      description: The state of the address
                      example: UT
                      type:
                      - string
                      - 'null'
                  type:
                  - object
                  - 'null'
                contactStatus:
                  description: A contact status, you need either the name or uid
                  properties:
                    name:
                      description: The status of the contact
                      example: Prospect
                      type: string
                    uid:
                      description: Podium unique identifier for contact status.
                      example: 00000000-0000-0000-0000-000000000000
                      format: uuid
                      type: string
                  type: object
                conversationUid:
                  description: Podium unique identifier for conversation.
                  example: 00000000-0000-0000-0000-000000000000
                  format: uuid
                  type: string
                email:
                  description: The email address of the resource
                  example: john.doe@podium.com
                  pattern: (.+)@(.+)\.(.+)
                  type: string
                locations:
                  description: List of location UIDs
                  items:
                    description: Podium unique identifier for location.
                    example: 00000000-0000-0000-0000-000000000000
                    format: uuid
                    type: string
                  type: array
                name:
                  description: The name of the resource
                  example: John Doe
                  type: string
                phoneNumber:
                  description: The phone number of the resource
                  example: '+18884441234'
                  pattern: ^\+[1-9]\d{1,15}$
                  type: string
              type: object
        description: Update contact params
        required: false
      responses:
        '202':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/contact_upsert'
                  metadata:
                    description: Additional response data.
                    properties:
                      url:
                        description: The resource URL.
                        example: https://www.podium.com/
                        type: string
                    type: object
                type: object
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                properties:
                  code:
                    description: Podium code for the error.
                    type: integer
                  message:
                    description: Specific details about the error.
                    type:
                    - string
                    - 'null'
                  moreInfo:
                    description: URL providing more information about the error.
                    type: string
                title: Error
                type: object
          description: Error response.
      summary: Update a contact
      tags:
      - Contact
  /v4/contacts/{identifier}/attributes/{uid}:
    delete:
      callbacks: {}
      description: 'Remove an attribute from a contact.


        Required scope: `write_contacts`.

        '
      operationId: contact_attribute.delete
      parameters:
      - description: Contact identifier
        example: john.doe@podium.com
        in: path
        name: identifier
        required: true
        schema:
          type: string
      - description: Podium unique identifier for attribute.
        in: path
        name: uid
        required: true
        schema:
          example: 00000000-0000-0000-0000-000000000000
          format: uuid
          type: string
      responses:
        '202':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/contact_attribute'
                  metadata:
                    description: Additional response data.
                    properties:
                      url:
                        description: The resource URL.
                        example: https://www.podium.com/
                        type: string
                    type: object
                type: object
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                properties:
                  code:
                    description: Podium code for the error.
                    type: integer
                  message:
                    description: Specific details about the error.
                    type:
                    - string
                    - 'null'
                  moreInfo:
                    description: URL providing more information about the error.
                    type: string
                title: Error
                type: object
          description: Error response.
      summary: Remove an attribute from a contact
      tags:
      - Contact
    patch:
      callbacks: {}
      description: 'Update the value of an existing attribute inside an existing contact.


        Required scope: `write_contacts`.

        '
      operationId: contact_attribute.update
      parameters:
      - description: Contact identifier
        example: john.doe@podium.com
        in: path
        name: identifier
        required: true
        schema:
          type: string
      - description: Podium unique identifier for attribute.
        in: path
        name: uid
        required: true
        schema:
          example: 00000000-0000-0000-0000-000000000000
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                value:
                  description: The value of the attribute.
                  example: Internal Contact ID
                  type: string
              required:
              - value
              type: object
        description: Update an attribute params
        required: true
      responses:
        '202':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/contact_attribute'
                  metadata:
                    description: Additional response data.
                    properties:
                      url:
                        description: The resource URL.
                        example: https://www.podium.com/
                        type: string
                    type: object
                type: object
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                properties:
                  code:
                    description: Podium code for the error.
                    type: integer
                  message:
                    description: Specific details about the error.
                    type:
                    - string
                    - 'null'
                  moreInfo:
                    description: URL providing more information about the error.
                    type: string
                title: Error
                type: object
          description: Error response.
      summary: Update a contact attribute inside a contact
      tags:
      - Contact
    post:
      callbacks: {}
      description: 'Add an existing attribute to an existing contact.


        Required scope: `write_contacts`.

        '
      operationId: contact_attribute.create
      parameters:
      - description: Contact identifier
        example: john.doe@podium.com
        in: path
        name: identifier
        required: true
        schema:
          type: string
      - description: Podium unique identifier for attribute.
        in: path
        name: uid
        required: true
        schema:
          example: 00000000-0000-0000-0000-000000000000
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                value:
                  description: The value of the attribute.
                  example: Internal Contact ID
                  type: string
              required:
              - value
              type: object
        description: Add an attribute params
        required: true
      responses:
        '202':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/contact_attribute'
                  metadata:
                    description: Additional response data.
                    properties:
                      url:
                        description: The resource URL.
                        example: https://www.podium.com/
                        type: string
                    type: object
                type: object
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                properties:
                  code:
                    description: Podium code for the error.
                    type: integer
                  message:
                    description: Specific details about the error.
                    type:
                    - string
                    - 'null'
                  moreInfo:
                    description: URL providing more information about the error.
                    type: string
                title: Error
                type: object
          description: Error response.
      summary: Add a contact attribute to a contact
      tags:
      - Contact
  /v4/contacts/{identifier}/tags/{uid}:
    delete:
      callbacks: {}
      description: 'Remove an existing tag from an existing contact.


        Required scope: `write_contacts`.

        '
      operationId: contact_tag.create
      parameters:
      - description: Contact identifier
        example: john.doe@podium.com
        in: path
        name: identifier
        required: true
        schema:
          type: string
      - description: Podium unique identifier for tag.
        in: path
        name: uid
        required: true
        schema:
          example: 00000000-0000-0000-0000-000000000000
          format: uuid
          type: string
      responses:
        '202':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/contact_tag'
                  metadata:
                    description: Additional response data.
                    properties:
                      url:
                        description: The resource URL.
                        example: https://www.podium.com/
                        type: string
                    type: object
                type: object
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                properties:
                  code:
                    description: Podium code for the error.
                    type: integer
                  message:
                    description: Specific details about the error.
                    type:
                    - string
                    - 'null'
                  moreInfo:
                    description: URL providing more information about the error.
                    type: string
                title: Error
                type: object
          description: Error response.
      summary: Remove an existing tag from an existing contact
      tags:
      - Contact
    post:
      callbacks: {}
      description: 'Add an existing tag to an existing contact.


        Required scope: `write_contacts`.

        '
      operationId: contact_tag.create (2)
      parameters:
      - description: Contact identifier
        example: john.doe@podium.com
        in: path
        name: identifier
        required: true
        schema:
          type: string
      - description: Podium unique identifier for tag.
        in: path
        name: uid
        required: true
        schema:
          example: 00000000-0000-0000-0000-000000000000
          format: uuid
          type: string
      responses:
        '202':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/contact_tag'
                  metadata:
                    description: Additional response data.
                    properties:
                      url

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