openapi: 3.2.0
info:
  description: Close CRM REST API
  title: Close Contacts API
  version: 1.0.0
servers:
- url: https://api.close.com/api/v1
security:
- ApiKeyAuth: []
- OAuth2: []
tags:
- name: contacts
  externalDocs:
    url: https://developer.close.com/api/resources/contacts
paths:
  /contact/:
    get:
      operationId: contacts_list
      tags:
      - contacts
      summary: List contacts
      parameters:
      - $ref: '#/components/parameters/LimitParam'
      - $ref: '#/components/parameters/SkipParam'
      - $ref: '#/components/parameters/FieldsParam'
      - in: query
        name: lead_id
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - created_by: null
                  date_created: '2013-02-01T00:54:51.300000+00:00'
                  date_updated: '2013-02-06T20:53:09.334000+00:00'
                  display_name: Tobias Fünke
                  emails:
                  - email: tobiasfunke@close.com
                    is_unsubscribed: false
                    type: office
                  id: cont_q4xYmlGhA3060dEl0NDJuHRxPMuVjqLn30AFSzh1fRk
                  name: Tobias Fünke
                  organization_id: orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH
                  phones: []
                  title: Blue Man Group (Understudy)
                  updated_by: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
                - created_by: null
                  custom.cf_j0P7kHmgFTZZnYBFtyPSZ3uQw4dpW8xKcW7Krps8atj: CEO
                  date_created: '2013-02-01T00:54:51.331000+00:00'
                  date_updated: '2013-02-06T20:53:01.954000+00:00'
                  display_name: Bruce Wayne
                  emails:
                  - email: thedarkknight@close.com
                    is_unsubscribed: true
                    type: office
                  id: cont_o0kP3Nqyq0wxr5DLWIEm8mVr6ZpI0AhonKLDG0V5Qjh
                  name: Bruce Wayne
                  organization_id: orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH
                  phones:
                  - country: US
                    phone: '+16503334444'
                    phone_formatted: +1 650-333-4444
                    type: office
                  title: The Dark Knight
                  updated_by: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
                - created_by: null
                  date_created: '2013-02-01T00:54:51.298000+00:00'
                  date_updated: '2013-02-06T20:48:55.240000+00:00'
                  display_name: Gob Bluth
                  emails:
                  - email: bluth@close.com
                    is_unsubscribed: false
                    type: office
                  id: cont_E7dYM0ecRoFQosxiPFz8IxazhN4k11uW8Sh1UsXjNjo
                  name: Gob Bluth
                  organization_id: orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH
                  phones: []
                  title: Magician
                  updated_by: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
                - created_by: null
                  date_created: '2013-02-01T00:54:51.203000+00:00'
                  date_updated: '2013-02-01T00:59:33.689000+00:00'
                  display_name: Close Support
                  emails:
                  - email: support@close.com
                    is_unsubscribed: false
                    type: office
                  id: cont_uw6ONU4iBcQg4TyqOKAwl0F1amULG9ZZsY57kHHdJNE
                  name: Close Support
                  organization_id: orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH
                  phones:
                  - country: US
                    is_unsubscribed: false
                    phone: '+18552567346'
                    phone_formatted: +1 855-256-7346
                    type: office
                  title: null
                  updated_by: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
                - created_by: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
                  date_created: '2013-02-08T05:02:39.552000+00:00'
                  date_updated: '2013-02-08T05:02:39.552000+00:00'
                  display_name: phil
                  emails:
                  - email: phil@close.com
                    is_unsubscribed: false
                    type: office
                  id: cont_eXZwc2SVL4G3xSR85jnfPny2ykvoAQndSyi1Doa2YLO
                  name: phil
                  organization_id: orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH
                  phones: []
                  title: ''
                  updated_by: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
                - created_by: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
                  date_created: '2013-02-20T05:30:24.844000+00:00'
                  date_updated: '2013-02-20T05:44:14.700000+00:00'
                  display_name: Gob
                  emails:
                  - email: gob@example.com
                    is_unsubscribed: false
                    type: office
                  id: cont_qpjDKxbN3WWsuhaJjg2Qr9pkqHqe1yviZ5BS0dEyz05
                  name: Gob
                  organization_id: orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH
                  phones:
                  - country: US
                    phone: '+18004445555'
                    phone_formatted: +1 800-444-5555
                    type: office
                  title: sr. vice president
                  updated_by: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
                - created_by: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
                  date_created: '2013-02-20T05:44:31.929000+00:00'
                  date_updated: '2013-02-20T05:44:31.929000+00:00'
                  display_name: Gob
                  emails:
                  - email: gob@example.com
                    is_unsubscribed: false
                    type: office
                  id: cont_kfaRMPzwQ9yAOn96gVGUxKRKqsYv6QJStoLhlDEpquY
                  name: Gob
                  organization_id: orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH
                  phones:
                  - country: US
                    phone: '+18004445555'
                    phone_formatted: +1 800-444-5555
                    type: office
                  title: sr. vice president
                  updated_by: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
                - created_by: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
                  date_created: '2013-02-20T05:44:35.625000+00:00'
                  date_updated: '2013-02-20T05:44:35.625000+00:00'
                  display_name: Gob
                  emails:
                  - email: gob@example.com
                    is_unsubscribed: false
                    type: office
                  id: cont_3lUrUYmceYjzeqrIqF5jpSppZemyxvgquE8Oq1kM6p0
                  name: Gob
                  organization_id: orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH
                  phones:
                  - country: US
                    phone: '+18004445555'
                    phone_formatted: +1 800-444-5555
                    type: office
                  title: sr. vice president
                  updated_by: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
                has_more: false
              schema:
                type: object
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/Contact'
                    type: array
                  has_more:
                    type: boolean
                required:
                - data
                - has_more
          description: Successful response
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Not found
    post:
      operationId: contacts_create
      tags:
      - contacts
      summary: Create a new contact
      description: 'Contacts belong to exactly one Lead (specified by `lead_id`). If you do not provide a `lead_id` then a new lead will be created, named after the contact.


        Custom field values can be set by including `custom.cf_*` keys in the request body, e.g. `"custom.cf_abc123": "value"`.'
      parameters:
      - $ref: '#/components/parameters/FieldsParam'
      requestBody:
        content:
          application/json:
            example:
              custom.cf_j0P7kHmgFTZZnYBFtyPSZ3uQw4dpW8xKcW7Krps8atj: Account Executive
              emails:
              - email: john@example.com
                type: office
              lead_id: lead_QyNaWw4fdSwxl5Mc5daMFf3Y27PpIcH0awPbC9l7uyo
              name: John Smith
              phones:
              - phone: '9045551234'
                type: mobile
              title: President
              urls:
              - type: url
                url: http://twitter.com/google/
            schema:
              $ref: '#/components/schemas/CreateContact'
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                created_by: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
                custom.cf_j0P7kHmgFTZZnYBFtyPSZ3uQw4dpW8xKcW7Krps8atj: Account Executive
                date_created: '2013-03-07T23:23:21.495000+00:00'
                date_updated: '2013-03-07T23:23:21.495000+00:00'
                display_name: John Smith
                emails:
                - email: john@example.com
                  is_unsubscribed: false
                  type: office
                id: cont_sNIdBgngvbdTTEN1mspKgUqKAWfbul4IITvnWoRw1T7
                name: John Smith
                organization_id: orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH
                phones:
                - country: US
                  phone: '+19045551234'
                  phone_formatted: +1 904-555-1234
                  type: mobile
                title: President
                updated_by: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
                urls:
                - type: url
                  url: http://twitter.com/google/
              schema:
                $ref: '#/components/schemas/Contact'
          description: Successful response
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Not found
  /contact/{id}/:
    get:
      operationId: contacts_get
      tags:
      - contacts
      summary: Fetch a single contact
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/FieldsParam'
      responses:
        '200':
          content:
            application/json:
              example:
                created_by: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
                date_created: '2013-02-20T05:44:35.625000+00:00'
                date_updated: '2013-02-20T05:44:35.625000+00:00'
                display_name: Gob
                emails:
                - email: gob@example.com
                  is_unsubscribed: false
                  type: office
                id: cont_3lUrUYmceYjzeqrIqF5jpSppZemyxvgquE8Oq1kM6p0
                lead_id: lead_etYl6PwL12hkj14567kjolJwZuZehb9b85EDH9CKuAI
                name: Gob
                organization_id: orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH
                phones:
                - country: US
                  phone: '+18004445555'
                  phone_formatted: +1 800-444-5555
                  type: office
                title: sr. vice president
                updated_by: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
              schema:
                $ref: '#/components/schemas/Contact'
          description: Successful response
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Not found
    put:
      operationId: contacts_update
      tags:
      - contacts
      summary: Update an existing contact
      description: 'Update a contact''s information. Custom field values can be set by including `custom.cf_*` keys in the request body, e.g. `"custom.cf_abc123": "value"`.


        For custom fields that accept multiple values, you can use `.add` or `.remove` suffixes to modify the existing list without replacing it:


        ```json

        { "custom.cf_v6S011I6MqcbVvB2FA5Nk8dr5MkL8sWuCiG8cUleO9c.add": "Wednesday" }

        ```'
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/FieldsParam'
      requestBody:
        content:
          application/json:
            example:
              name: Johnny Smith
            schema:
              $ref: '#/components/schemas/UpdateContact'
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                created_by: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
                custom.cf_j0P7kHmgFTZZnYBFtyPSZ3uQw4dpW8xKcW7Krps8atj: Sales Rep
                date_created: '2013-03-07T23:23:21.495000+00:00'
                date_updated: '2013-03-08T13:13:21.495000+00:00'
                display_name: Johnny Smith
                emails:
                - email: john@example.com
                  is_unsubscribed: false
                  type: office
                id: cont_sNIdBgngvbdTTEN1mspKgUqKAWfbul4IITvnWoRw1T7
                lead_id: lead_QyNaWw4fdSwxl5Mc5daMFf3Y27PpIcH0awPbC9l7uyo
                name: Johnny Smith
                organization_id: orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH
                phones:
                - country: US
                  phone: '+19045551234'
                  phone_formatted: +1 904-555-1234
                  type: mobile
                title: President
                updated_by: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
                urls:
                - type: url
                  url: http://twitter.com/google/
              schema:
                $ref: '#/components/schemas/Contact'
          description: Successful response
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Not found
    delete:
      operationId: contacts_delete
      tags:
      - contacts
      summary: Delete a contact
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Not found
components:
  schemas:
    ContactPhone:
      title: ContactPhone
      type: object
      properties:
        country:
          title: Country
          anyOf:
          - type: string
          - type: 'null'
        outbound_sms_blocked:
          title: Outbound SMS Blocked
          type: boolean
        phone:
          title: Phone
          type: string
        phone_formatted:
          title: Phone Formatted
          type: string
        type:
          title: Type
          type: string
        tz_ids:
          title: TZ IDs
          type: array
          items:
            type: string
      required:
      - phone
      - type
    CreateContact:
      type: object
      properties:
        created_by:
          type:
          - 'null'
          - string
        date_created:
          type:
          - 'null'
          - string
          format: date-time
        emails:
          type:
          - array
          - 'null'
          maxItems: 100
          items:
            type: object
            properties:
              email:
                type: string
                format: email
              type:
                type: string
            required:
            - email
        lead_id:
          type:
          - 'null'
          - string
        name:
          type:
          - 'null'
          - string
          maxLength: 1000
        phones:
          type:
          - array
          - 'null'
          maxItems: 100
          items:
            type: object
            properties:
              phone:
                description: Phone number in E.164 format
                type:
                - 'null'
                - string
              type:
                type: string
        timezone:
          description: IANA timezone identifier
          type:
          - 'null'
          - string
        title:
          type:
          - 'null'
          - string
          maxLength: 1000
        urls:
          type:
          - array
          - 'null'
          maxItems: 100
          items:
            type: object
            properties:
              type:
                type: string
              url:
                type: string
                format: uri
            required:
            - url
      additionalProperties: false
      patternProperties:
        ^custom\.:
          not:
            type: object
    WorkflowRunStatus:
      title: WorkflowRunStatus
      type: string
      enum:
      - active
      - paused
      - finished
      - goal
      - error
    ContactUrl:
      title: ContactUrl
      type: object
      properties:
        type:
          title: Type
          type: string
        url:
          title: URL
          type: string
      required:
      - type
      - url
    Contact:
      title: Contact
      type: object
      properties:
        created_by:
          title: Created By
          anyOf:
          - type: string
          - type: 'null'
        date_created:
          title: Date Created
          type: string
          format: date-time
        date_updated:
          title: Date Updated
          type: string
          format: date-time
        display_name:
          title: Display Name
          type: string
        emails:
          title: Emails
          type: array
          items:
            $ref: '#/components/schemas/ContactEmail'
        id:
          title: ID
          type: string
        integration_links:
          title: Integration Links
          type: array
          items:
            $ref: '#/components/schemas/RenderedIntegrationLink'
        lead_id:
          title: Lead ID
          default: null
          anyOf:
          - type: string
          - type: 'null'
        lead_suggestions_operation_id:
          title: Lead Suggestions Operation ID
          anyOf:
          - type: string
          - type: 'null'
        name:
          title: Name
          anyOf:
          - type: string
          - type: 'null'
        organization_id:
          title: Organization ID
          type: string
        phones:
          title: Phones
          type: array
          items:
            $ref: '#/components/schemas/ContactPhone'
        recent_calls:
          title: Recent Calls
          type: array
          items:
            $ref: '#/components/schemas/ContactRecentCall'
        subscriptions:
          title: Subscriptions
          type: array
          items:
            $ref: '#/components/schemas/BasicSubscriptionInfoForContact'
        timezone:
          title: Timezone
          anyOf:
          - type: string
          - type: 'null'
        timezone_source:
          title: Timezone Source
          anyOf:
          - type: string
          - type: 'null'
        title:
          title: Title
          anyOf:
          - type: string
          - type: 'null'
        updated_by:
          title: Updated By
          anyOf:
          - type: string
          - type: 'null'
        urls:
          title: URLs
          type: array
          items:
            $ref: '#/components/schemas/ContactUrl'
      required:
      - created_by
      - date_created
      - date_updated
      - display_name
      - id
      - name
      - organization_id
      - title
      - updated_by
    CallStatus:
      title: CallStatus
      description: Current status of the call.
      type: string
      enum:
      - created
      - in-progress
      - completed
      - cancel
      - no-answer
      - busy
      - failed
      - timeout
    UpdateContact:
      type: object
      properties:
        emails:
          type:
          - array
          - 'null'
          maxItems: 100
          items:
            type: object
            properties:
              email:
                type: string
                format: email
              type:
                type: string
            required:
            - email
        lead_id:
          type:
          - 'null'
          - string
        name:
          type:
          - 'null'
          - string
          maxLength: 1000
        phones:
          type:
          - array
          - 'null'
          maxItems: 100
          items:
            type: object
            properties:
              phone:
                description: Phone number in E.164 format
                type:
                - 'null'
                - string
              type:
                type: string
        timezone:
          description: IANA timezone identifier
          type:
          - 'null'
          - string
        title:
          type:
          - 'null'
          - string
          maxLength: 1000
        urls:
          type:
          - array
          - 'null'
          maxItems: 100
          items:
            type: object
            properties:
              type:
                type: string
              url:
                type: string
                format: uri
            required:
            - url
      additionalProperties: false
      patternProperties:
        ^custom\.:
          not:
            type: object
    StatusReason:
      title: StatusReason
      description: Reason for each higher level status on a Workflow run.
      type: string
      enum:
      - manual
      - pending-call-timed-out
      - bulk-action
      - rate-limited
      - sequence-deleted
      - workflow-paused
      - filter-not-matched
      - insufficient-ai-credit-balance
      - reply-received
      - call-answered
      - meeting-booked
      - lead-status-changed
      - outcome-met
      - account-invalid
      - account-failures
      - sending-throttled-too-long
      - membership-inactive
      - send-as-error
      - email-bounced
      - call-failed
      - sms-failed
      - no-user-phone
      - billing-error
      - assignment-field-invalid
      - lead-status-field-invalid
      - assignees-missing
      - run-as-disabled
      - lead-not-visible
      - internal-error
      - field-mapping-error
      - filter-config-invalid
      - email-ai-generation-failed
    WorkflowStatus:
      title: WorkflowStatus
      type: string
      enum:
      - active
      - paused
      - draft
    BasicSubscriptionInfoForContact:
      title: BasicSubscriptionInfoForContact
      type: object
      properties:
        contact_email:
          title: Contact Email
          anyOf:
          - type: string
          - type: 'null'
        date_created:
          title: Date Created
          type: string
          format: date-time
        initial_email_id:
          title: Initial Email ID
          anyOf:
          - type: string
          - type: 'null'
        sequence_id:
          title: Sequence ID
          type: string
        sequence_name:
          title: Sequence Name
          type: string
        sequence_status:
          $ref: '#/components/schemas/WorkflowStatus'
        start_date:
          title: Start Date
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
        subscription_id:
          title: Subscription ID
          type: string
        subscription_status:
          $ref: '#/components/schemas/WorkflowRunStatus'
        subscription_status_reason:
          anyOf:
          - $ref: '#/components/schemas/StatusReason'
          - type: 'null'
      required:
      - contact_email
      - date_created
      - initial_email_id
      - sequence_id
      - sequence_name
      - sequence_status
      - start_date
      - subscription_id
      - subscription_status
      - subscription_status_reason
    ContactEmail:
      title: ContactEmail
      type: object
      properties:
        email:
          title: Email
          type: string
        is_unsubscribed:
          title: Is Unsubscribed
          type: boolean
        type:
          title: Type
          type: string
      required:
      - email
      - is_unsubscribed
      - type
    ContactRecentCall:
      title: ContactRecentCall
      type: object
      properties:
        dialer_id:
          title: Dialer ID
          anyOf:
          - type: string
          - type: 'null'
        duration:
          title: Duration
          type: integer
        finish_timestamp:
          title: Finish Timestamp
          type: string
          format: date-time
        id:
          title: ID
          type: string
        status:
          $ref: '#/components/schemas/CallStatus'
      required:
      - dialer_id
      - duration
      - finish_timestamp
      - id
      - status
    RenderedIntegrationLink:
      title: RenderedIntegrationLink
      type: object
      properties:
        name:
          title: Name
          type: string
        url:
          title: Url
          type: string
      required:
      - name
      - url
  parameters:
    FieldsParam:
      description: Comma-separated list of fields to include in the response.
      in: query
      name: _fields
      required: false
      schema:
        type: string
    LimitParam:
      description: Number of results to return.
      in: query
      name: _limit
      required: false
      schema:
        default: 100
        type: integer
    SkipParam:
      description: Number of results to skip before returning, for pagination.
      in: query
      name: _skip
      required: false
      schema:
        default: 0
        type: integer
  securitySchemes:
    ApiKeyAuth:
      description: Use your API key as the username and leave the password empty.
      scheme: basic
      type: http
    OAuth2:
      flows:
        authorizationCode:
          authorizationUrl: https://app.close.com/oauth2/authorize/
          scopes:
            all.full_access: Full access to all resources
            offline_access: Request a refresh token
          tokenUrl: https://api.close.com/oauth2/token/
      type: oauth2