openapi: 3.2.0
info:
  title: Reference List Contacts API
  version: '2.0'
  contact:
    name: Sendlane
    url: https://sendlane.com
    email: support@sendlane.com
  description: Sendlane V2 API
servers:
- url: https://api.sendlane.com/v2
  description: Sendlane
security:
- BearerToken: []
tags:
- name: List Contacts
paths:
  /lists/{listId}/contacts:
    parameters:
    - schema:
        type: integer
      name: listId
      in: path
      required: true
    - $ref: '#/components/parameters/from'
    - $ref: '#/components/parameters/to'
    post:
      summary: Create List Contact
      operationId: post-lists-listId-contacts
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AcceptedResponse.v2'
      description: Add a contact to a list (In order to add **SMS Consent** to the request, the **Contact SMS Consent** endpoint must first be enabled in your account by contacting support)
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              description: ''
              type: object
              properties:
                contacts:
                  type: array
                  uniqueItems: true
                  minItems: 1
                  items:
                    $ref: '#/components/schemas/ListContact.v2'
              required:
              - contacts
            examples:
              Add Contact:
                value:
                  contacts:
                  - email: user@example.com
                    first_name: string
                    last_name: string
                    phone: '+15555555555'
                    email_consent: true
                    sms_consent: []
                    tag_ids:
                    - 1
                    tagNames:
                    - tag
                    custom_fields: []
              Add Multiple Contacts:
                value:
                  contacts:
                  - email: user@example.com
                    first_name: string
                    last_name: string
                    phone: '+15555555555'
                    email_consent: true
                    sms_consent: []
                    tag_ids:
                    - 1
                    custom_fields:
                    - key: birthday
                      value: '2022-12-12'
                    - key: alias
                      value: J.Doe
        description: array of contact objects
      tags:
      - List Contacts
    get:
      summary: Get List Contacts
      operationId: get-lists-listId-contacts
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactIndexResponse.v2'
      description: Get contacts from list
      tags:
      - List Contacts
  /lists/{listId}/contacts/{contactId}:
    parameters:
    - schema:
        type: integer
      name: contactId
      in: path
      required: true
    get:
      summary: Get List Contact
      description: Get List Contact
      tags:
      - List Contacts
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactResponse.v2'
      operationId: get-lists-listId-contacts-contactId
      parameters: []
    delete:
      description: Delete Contact from List
      summary: Delete Contact from List
      operationId: delete-lists-listId-contacts-contactId
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AcceptedResponse.v2'
      tags:
      - List Contacts
components:
  schemas:
    ListContact.v2:
      description: ''
      type: object
      x-examples:
        List Contact:
          email: user@example.com
          first_name: string
          last_name: string
          phone: '+15555555555'
          email_consent: true
          sms_consent: array
          tag_ids:
          - 1
          custom_fields:
          - key: string
            value: string
      title: List Contact
      properties:
        email:
          type: string
          minLength: 1
          format: email
        first_name:
          type: string
          minLength: 1
        last_name:
          type: string
          minLength: 1
        phone:
          type: string
          example: '+15555555555'
        email_consent:
          type: boolean
          example: true
        sms_consent:
          type: array
          items:
            $ref: '#/components/schemas/SmsConsentField.v2'
        tag_ids:
          type: array
          uniqueItems: true
          items:
            type: integer
            example: 1
        custom_fields:
          type: array
          uniqueItems: false
          items:
            $ref: '#/components/schemas/ListContactCustomField.v2'
      required-without-phone:
      - email
      required-without-email:
      - phone
    ContactResponse.v2:
      title: Contact Response
      type: object
      x-examples:
        Contact Response:
          data:
            id: 1
            email: string
            first_name: string
            last_name: string
            phone: string
            sms_consent: []
            subscribed: true
            suppressed: false
      properties:
        data:
          $ref: '#/components/schemas/Contact.v2'
      required:
      - data
    PaginatorMeta.v2:
      description: ''
      type: object
      x-examples: {}
      properties:
        current_page:
          type: integer
          readOnly: true
        from:
          type: integer
          readOnly: true
        last_page:
          type: integer
          readOnly: true
        path:
          type: string
          minLength: 1
          readOnly: true
        per_page:
          type: integer
          readOnly: true
        to:
          type: integer
          readOnly: true
        total:
          type: integer
          readOnly: true
      title: Paginator Meta
    PaginatorLinks.v2:
      description: ''
      type: object
      x-examples: {}
      properties:
        first:
          type: string
          minLength: 1
          format: uri
          readOnly: true
        last:
          type: string
          minLength: 1
          format: uri
          readOnly: true
        prev:
          type: string
          minLength: 1
          format: uri
          readOnly: true
        next:
          type: string
          minLength: 1
          format: uri
          readOnly: true
      title: Paginator Links
    CustomField.v2:
      title: CustomField
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
        created_at:
          type: string
      required:
      - name
    ListContactCustomField.v2:
      title: CustomField
      type: object
      properties:
        id:
          type: integer
        value:
          type: string
    SmsConsentField.v2:
      title: SMS Consent Field
      type: object
      properties:
        consent_type:
          type: string
          example: sms_keyword,web_form,integration
        ip_address:
          type: string
          format: ip
          example: 12.34.567.89
        optin_date:
          type: string
          format: date-time
          example: 202X-01-01 09:00:00
        sms_consent:
          type: boolean
          example: true
        user_agent:
          type: string
          example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_5_3 rv:6.0; sl-SI) AppleWebKit/533.24.5 (KHTML, like Gecko) Version/4.0 Safari/533.24.5
        optin_url:
          type: string
          format: url
          example: http://example.com/optin-url
        consent_language:
          type: string
          description: text snippet or url to language
          example: http://example.com/terms-of-service
        cookie_uuid:
          type: string
          example: 0H28vBAcx8PBbAmXqamTjY3BDyvMcyN8Xy5nAquShpB
    Contact.v2:
      description: ''
      type: object
      title: Contact
      properties:
        id:
          type: integer
        custom_fields:
          type: array
          items:
            $ref: '#/components/schemas/CustomField.v2'
        email:
          type: string
        first_name:
          type: string
        integration_customer:
          type: array
        last_name:
          type: string
        lifetime_value:
          type: number
        lists:
          type: array
          items:
            $ref: '#/components/schemas/ContactList.v2'
        phone:
          type: string
        sms_consent:
          type: array
        subscribed:
          type: boolean
        suppressed:
          type: boolean
        tags:
          type: array
          items:
            $ref: '#/components/schemas/ContactTag.v2'
    ContactList.v2:
      title: Contact List
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
    ContactTag.v2:
      title: Contact Tag
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
    ContactIndexResponse.v2:
      title: ContactIndexResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Contact.v2'
        links:
          $ref: '#/components/schemas/PaginatorLinks.v2'
        meta:
          $ref: '#/components/schemas/PaginatorMeta.v2'
      x-examples:
        Response:
          data:
          - id: 1
            custom_fields: []
            email: string
            first_name: string
            integration_customer: []
            last_name: string
            lifetime_value: 0
            lists: []
            phone: string
            subscribed: boolean
            suppressed: boolean
            tags: []
          links:
            first: string
            last: string
            prev: string
            next: string
          meta:
            current_page: 1
            from: 1
            last_page: 1
            path: string
            per_page: 100
            to: 1
            total: 1
    AcceptedResponse.v2:
      title: Accepted Response
      type: object
      properties:
        message:
          type: string
      x-examples:
        Success Response:
          message: Successfully handled request
  parameters:
    to:
      schema:
        type: string
        format: date-time
      name: to
      description: Ending datetime.
      in: query
      required: false
      example: '`2024-12-04T12:30:40-05:00` or `2024-12-04T12:30:40%2b05:00` or `2024-12-04T12:00:00%2b00:00` or `2024-12-04T12:00:00Z`'
    from:
      schema:
        type: string
        format: date-time
      name: from
      description: Starting datetime. Required if the "to" parameter is in the query.
      in: query
      required: false
      example: '`2024-12-04T12:30:40-05:00` or `2024-12-04T12:30:40%2b05:00` or `2024-12-04T12:00:00%2b00:00` or `2024-12-04T12:00:00Z`'
  securitySchemes:
    BearerToken:
      name: Authorization
      type: apiKey
      in: header
      description: API token sent in the Authorization header with the value "Bearer {apiToken}"
    OtherAccountBearerToken:
      name: Authorization-Destination
      type: apiKey
      in: header
      description: API token for other account sent in the Authorization-Destination header with the value "Bearer {apiToken}"