openapi: 3.2.0
info:
  title: Transmit SMS Contacts & Lists API
  description: '<p>With so many SMS APIs on the market today, you might think that they all do the same thing: send text messages. But with our flexible and powerful suite of APIs, you can do more than that.</p>'
  version: 1.0.0
servers:
- url: https://api.transmitsms.com
tags:
- name: Contacts & Lists
paths:
  /add-contacts-bulk.json:
    post:
      tags:
      - Contacts & Lists
      summary: Bulk Add Contacts from CSV File
      description: "Add bulk contacts to a list from a file\n\nThe add-contacts-bulk request can be used to add a CSV file of contacts to an existing list. It can also be used to create a new list and upload a CSV file of contacts to it. If a contact is added that already exists in a list, any existing data will be updated.\n\n**The return code 200 is only used to indicate that the API call has successfully hit our server. It in no way indicates if the contacts have been added\\updated successfully.\nTo find the status of an upload, including error messages, you must use the add-contacts-bulk-progress endpoint.**\n\n```\nCSV File Format and Example:\n        Firstname,Lastname,Mobile,\"Custom Field 1\"\n        Jane,Doe,61412345678,10.44\n\nThe minimum required for successful import is Mobile.\n\nThe order above must be followed.\n```"
      security:
      - basicAuth: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - list_id
              - name
              properties:
                list_id:
                  type: integer
                  description: ID of the list to be added to. This ID is the numerical reference to one of your recipient lists. Required if name is not set.
                name:
                  type: string
                  description: Name of the list to create and add contacts to. If set, a new list will be created with this name. The list ID will be returned in the API response. Required if list_id is not set.
                countrycode:
                  type: string
                  description: Format the number in international format. 2-letter ISO 3166 format country code or country name. Automatically formats numbers to international format required for reliable SMS delivery.
                file_url:
                  type: string
                  description: "URL location of the CSV file containing the contact list.\n\n- Must be a direct URL to the file, cannot be a redirected URL. \n- Cannot be a file on a local machine.\n- File must contain a column with the header ‘mobile’\n- To maximise API performance no error will be returned if call fails. ID returned in response will be automatically deleted.\n- To get status of call use add-contacts-bulk-progress\n- Basic auth can be used to secure file eg. https://username:password@domain.com/file\n"
                field_n:
                  type: string
                  description: 'Create or map a custom field.


                    - There are 10 custom field slots available. The value n is the number of the custom field slot 1 through 10.

                    - Create a field name using field_n=name e.g. field_1=email.

                    - Headers in your file that match the custom field name will be automatically mapped. e.g. Column in CSV file named email will be automatically mapped to field_1=email.

                    - If name contains spaces or symbols, other than letters or numbers, these must be URL encoded

                    '
      responses:
        '200':
          description: Successful response containing the list ID and error details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  list_id:
                    type: integer
                    description: Numeric ID of the list.
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Error code indicating the status of the operation.
                      description:
                        type: string
                        description: Description of the error status.
  /add-list.json:
    post:
      tags:
      - Contacts & Lists
      summary: Add List
      description: Create New Contact List
      security:
      - basicAuth: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  description: A unique name for the list.
                  example: MyList
                field_n:
                  type: string
                  description: Custom field name. Firstname and lastname are created by default. There can be up to 10 extra custom fields. 'n' is an integer between 1 and 10.
                  example: email
                response_style:
                  type: string
                  description: Indicates the response style. response_style = 'array' returns custom field lists as an array.
                  enum:
                  - array
                  default: null
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: A unique identifier for the list.
                    example: 12345
                  name:
                    type: string
                    description: Custom field name. Firstname and lastname are created by default. There can be up to 10 extra custom fields. 'n' is an integer between 1 and 10.
                    example: email
                  created:
                    type: string
                    format: date-time
                    description: Date and time list was created. Returned in ISO8601 format YYYY-MM-DD HH:MM:SS in UTC Timezone.
                    example: '2024-04-23T12:34:56Z'
                  members_active:
                    type: integer
                    description: Number of active members in the list. Always returns 0 for a new list.
                    example: 0
                  fields:
                    type: array
                    items:
                      type: string
                    description: Names of created custom fields.
                    example:
                    - email
                    - phone
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        CODE:
                          type: string
                          description: Error code.
                          example: MISSING_PARAM
                        HEADER:
                          type: integer
                          description: HTTP status code.
                          example: 400
                        DESCRIPTION:
                          type: string
                          description: Description of the error.
                          example: Field parameter is missing (eg. field_n)
              examples:
                example-0:
                  summary: Example 1
                  value:
                    id: 4213644
                    name: Customer List
                    created: '2020-06-24 05:25:48'
                    members_active: 0
                    fields:
                      field_1: Email
                      field_2: Postcode
                      field_3: ID
                    error:
                      code: SUCCESS
                      description: OK
                example-1:
                  summary: Example 3
                  value:
                    id: 4236712
                    name: New Contacts 2
                    created: '2020-06-30 05:02:15'
                    members_active: 0
                    fields:
                    - name: field_1
                      value: FirstName
                    - name: field_2
                      value: LastName
                    error:
                      code: SUCCESS
                      description: OK
            text/plain:
              schema:
                type: string
              example: "<?xml version=\"1.0\"?>\n<response>\n    <id>4213652</id>\n    <name>User List</name>\n    <created>2020-06-24 05:26:59</created>\n    <members_active>0</members_active>\n    <fields>\n        <field_1>Email</field_1>\n        <field_2>Postcode</field_2>\n        <field_3>ID</field_3>\n    </fields>\n    <error>\n        <code>SUCCESS</code>\n        <description>OK</description>\n    </error>\n</response>"
  /add-field-to-list.json:
    post:
      tags:
      - Contacts & Lists
      summary: Add Field to List
      description: Add or update custom fields on an existing list
      security:
      - basicAuth: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - list_id
              - field_n
              properties:
                list_id:
                  type: integer
                  description: ID of the list to add to.
                  example: 12345
                field_n:
                  type: array
                  items:
                    type: string
                  description: Custom field names. Firstname and lastname are created by default. There can be up to 10 extra custom fields. 'n' is an integer between 1 and 10.
                  example: address
                  minItems: 1
                response_style:
                  type: string
                  description: Indicates the response style. If set to response_style='array', custom field lists are returned as an array.
                  example: array
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  custom_n:
                    type: array
                    items:
                      type: string
                    description: Custom field names created.
                    example:
                    - email
                    - phone
                  id:
                    type: integer
                    description: ID of the list added to.
                    example: 12345
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Error code.
                        example: MISSING_PARAM
                      header:
                        type: integer
                        description: HTTP status code.
                        example: 400
                      description:
                        type: string
                        description: Description of the error.
                        example: Field parameter is missing (e.g., field_n)
              examples:
                example-0:
                  summary: Example 1
                  value:
                    custom_4: Handset
                    id: 4213644
                    error:
                      code: SUCCESS
                      description: OK
                example-1:
                  summary: Example 3
                  value:
                    fields:
                    - name: custom_4
                      value: Address
                    id: 4213652
                    error:
                      code: SUCCESS
                      description: OK
  /remove-list.json:
    post:
      tags:
      - Contacts & Lists
      summary: Remove List
      description: Delete a list and its contacts
      security:
      - basicAuth: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                list_id:
                  type: integer
                  description: Numeric ID of the list to be removed. List IDs can be retrieved with the get-lists request.
              required:
              - list_id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: SUCCESS
                      description:
                        type: string
                        example: OK
            text/plain:
              schema:
                type: string
              example: "<?xml version=\"1.0\"?>\n<response>\n    <error>\n        <code>SUCCESS</code>\n        <description>OK</description>\n    </error>\n</response>"
  /add-to-list.json:
    post:
      tags:
      - Contacts & Lists
      summary: Add Contact to List
      description: 'Adds a new contact to a list

        If a contact is added that already exists it will be ignored, not updated.'
      security:
      - basicAuth: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - list_id
              - msisdn
              properties:
                list_id:
                  type: integer
                  description: Numeric ID of the list to be added to. List IDs can be retrieved with the get-lists request.
                  example: 12345
                msisdn:
                  type: string
                  description: Mobile number being added to the list. Invalid numbers will be ignored. Number must be defined in E.164 international format. You can use the countrycode parameter to format numbers that are in local format.
                countrycode:
                  type: string
                  description: '2 letter ISO 3166 format country code or country name. Automatically formats numbers to international format required for reliable SMS delivery. eg. In Australia 0422222222 will become 6142222222 when set to AU or Australia. If not set to numbers must be defined in E.164 international format.


                    | COUNTRY       | COUNTRY CODE | LOCAL       | INTERNATIONAL  |

                    |---------------|--------------|-------------|----------------|

                    | Australia     | au           | 0491570156  | 61491570156    |

                    | New Zealand   | nz           | 0212670129  | 64212670129    |

                    | United Kingdom| gb           | 0750017696  | 44750017696    |

                    | United States | us           | 2513551145  | 12513551145    |

                    '
                  example: AU
                first_name:
                  type: string
                  description: First name of the contact being added.
                  example: John
                last_name:
                  type: string
                  description: Last name of the contact being added.
                  example: Doe
                field_n:
                  type: string
                  description: 'Custom field name. Firstname and lastname are created by default. There can be up to 10 extra custom fields. n is an integer between 1 and 10.

                    '
                  example: Email
                response_style:
                  type: string
                  description: 'Determines the response style. ''array'' returns custom field lists as an array.

                    '
                  example: array
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  list_id:
                    type: integer
                    description: Numeric ID of the list that contact was added to.
                  msisdn:
                    type: string
                    description: Mobile number of contact that was added.
                  firstname:
                    type: string
                    description: First name of contact added.
                  lastname:
                    type: string
                    description: Last name of contact added.
                  created_at:
                    type: string
                    description: Date and time contact was added. Returned in ISO8601 format YYYY-MM-DD HH:MM:SS in UTC Timezone.
                  status:
                    type: string
                    description: Status of contact. This is always set to active with this request.
                  fields:
                    type: object
                    description: Values assigned to custom fields.
                  errors:
                    type: object
                    properties:
                      BAD_MOBILE:
                        type: string
                        description: The mobile provided is invalid.
                      BAD_MOBILE_COUNTRY:
                        type: string
                        description: The country of the mobile provided is unavailable.
                      OPTOUT:
                        type: string
                        description: The recipient provided was previously opted out.
                      DUPLICATE_DELETED:
                        type: string
                        description: The recipient provided was previously deleted.
                      KEY_EXISTS:
                        type: string
                        description: Contact with such mobile already exists.
              examples:
                example-0:
                  summary: Example 1
                  value:
                    list_id: 4213644
                    msisdn: 61429625067
                    first_name: ''
                    last_name: ''
                    created_at: '2020-06-24 07:06:57'
                    status: active
                    fields:
                      Email: Telstra
                      Postcode: ''
                      ID: ''
                      Handset: ''
                    error:
                      code: SUCCESS
                      description: OK
                example-1:
                  summary: Example 3
                  value:
                    list_id: 4213652
                    msisdn: 61429625067
                    first_name: ''
                    last_name: ''
                    created_at: '2020-06-30 05:11:12'
                    status: active
                    fields:
                    - name: Email
                      value: ID
                    - name: Postcode
                      value: Address
                    - name: ID
                      value: ''
                    - name: Address
                      value: ''
                    error:
                      code: SUCCESS
                      description: OK
            text/plain:
              schema:
                type: string
              example: "<?xml version=\"1.0\"?>\n<response>\n    <list_id>4213644</list_id>\n    <msisdn>61429720235</msisdn>\n    <first_name/>\n    <last_name/>\n    <created_at>2020-06-24 07:09:03</created_at>\n    <status>active</status>\n    <fields>\n        <Email>Telstra</Email>\n        <Postcode/>\n        <ID/>\n        <Handset/>\n    </fields>\n    <error>\n        <code>SUCCESS</code>\n        <description>OK</description>\n    </error>\n</response>"
  /edit-list-member.json:
    post:
      tags:
      - Contacts & Lists
      summary: Update Contact
      description: 'Edit a contact that exists on a list

        Used for adding new or updated custom data to a contact on a list.'
      security:
      - basicAuth: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - list_id
              - msisdn
              properties:
                list_id:
                  type: integer
                  description: Numeric ID of the list to be added to. This ID is the numerical reference to one of your recipient lists. It can be found in the URL and displayed on a destination list page in your account. A list ID can also be created using the add-list call.
                  example: 12345
                msisdn:
                  type: string
                  description: Mobile number of contact being updated. Invalid numbers will be ignored. Number must be defined in E.164 international format.
                  example: '61478038915'
                first_name:
                  type: string
                  description: First name of contact being added.
                last_name:
                  type: string
                  description: Last name of contact being added.
                field_n:
                  type: string
                  description: Custom field name. Firstname and lastname are created by default. There can be up to 10 extra custom fields. n is an integer between 1 and 10.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  list_id:
                    type: integer
                    description: Numeric ID of the list that contact was added to.
                  msisdn:
                    type: string
                    description: Mobile number of contact that was added.
                  firstname:
                    type: string
                    description: First name of contact added.
                  lastname:
                    type: string
                    description: Last name of contact added.
                  created_at:
                    type: string
                    description: Date and time contact was added. Returned in ISO8601 format (YYYY-MM-DD HH:MM:SS) in UTC Timezone.
                  status:
                    type: string
                    description: Status of contact. This is always set to active with this request.
                  fields:
                    type: object
                    description: Values assigned to custom fields.
                  errors:
                    type: object
                    description: Error messages related to this call. See the API Introduction for general errors.
                    properties:
                      BAD_MOBILE:
                        type: string
                        description: The mobile provided is invalid.
                      BAD_MOBILE_COUNTRY:
                        type: string
                        description: The country of the mobile provided is unavailable.
                      OPTOUT:
                        type: string
                        description: The recipient provided was previously opted out.
                      DUPLICATE_DELETED:
                        type: string
                        description: The recipient provided was previously deleted.
                      KEY_EXISTS:
                        type: string
                        description: Contact with such mobile already exists.
              example:
                list_id: 4213644
                msisdn: 61429720235
                first_name: ''
                last_name: ''
                created_at: '2020-06-24 07:09:03'
                status: active
                fields:
                  Email: Optus
                  Postcode: ''
                  ID: ''
                  Handset: ''
                error:
                  code: SUCCESS
                  description: OK
            text/plain:
              schema:
                type: string
              example: "<?xml version=\"1.0\"?>\n<response>\n    <list_id>4213644</list_id>\n    <msisdn>61429720235</msisdn>\n    <first_name/>\n    <last_name/>\n    <created_at>2020-06-24 07:09:03</created_at>\n    <status>active</status>\n    <fields>\n        <Email>Optus</Email>\n        <Postcode/>\n        <ID/>\n        <Handset/>\n    </fields>\n    <error>\n        <code>SUCCESS</code>\n        <description>OK</description>\n    </error>\n</response>"
  /delete-from-list.json:
    post:
      tags:
      - Contacts & Lists
      summary: Remove Contact
      description: Delete contact from one or all lists
      security:
      - basicAuth: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - msisdn
              properties:
                list_id:
                  type: integer
                  description: Numeric ID of list to remove contact from. If set to 0 (zero), the contact will be removed from all lists.
                msisdn:
                  type: string
                  description: Mobile number of contact being removed. Number must be defined in E.164 international format. You can use countrycode parameter to format numbers that are in local format.
                countrycode:
                  type: string
                  description: 'Format the to number in international format. 2 letter ISO 3166 format country code or country name. Automatically formats numbers to international format required for reliable SMS delivery. If not set, numbers must be defined in E.164 international format.


                    | COUNTRY        | COUNTRY CODE | LOCAL      | INTERNATIONAL  |

                    | -------------- | ------------ | ---------- | -------------- |

                    | Australia      | au           | 0491570156 | 61491570156    |

                    | New Zealand    | nz           | 0212670129 | 64212670129    |

                    | United Kingdom | gb           | 0750017696 | 44750017696    |

                    | United States  | us           | 2513551145 | 12513551145    |

                    '
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  list_ids:
                    type: array
                    description: One or more list ID's that contact was removed from
                    items:
                      type: integer
                  error:
                    type: object
                    description: Error messages related to this call
                    properties:
                      NOT_FOUND:
                        type: string
                        description: Contact with such mobile does not exist in this list
              examples:
                example-0:
                  summary: Example 2
                  value:
                    list_ids:
                    - 4263168
                    error:
                      code: SUCCESS
                      description: OK
                example-1:
                  summary: Example 3
                  value:
                    list_ids:
                    - 4263168
                    error:
                      code: SUCCESS
                      description: OK
            text/plain:
              schema:
                type: string
              example: "<?xml version=\"1.0\"?>\n<response>\n    <list_ids>\n        <item>4213644</item>\n    </list_ids>\n    <error>\n        <code>SUCCESS</code>\n        <description>OK</description>\n    </error>\n</response>"
  /optout-list-member.json:
    post:
      tags:
      - Contacts & Lists
      summary: Opt Out/Unsubscribe Contact
      description: "Opt Out List Member\n\nUnsubscribe contact from one or all lists  \nIf sending marketing by law you must enable an unsubscribe method. [Anti-Spam Policy](https://help.kudosity.com/s/article/44001077041-anti-spam-policy)"
      security:
      - basicAuth: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - msisdn
              properties:
                list_id:
                  type: integer
                  description: 'Numeric ID of list to opt out contact from. If set to 0 (zero), the contact will be opted out from all lists. If your Global Opt Out (GOO) list is switched on, unsubscribing from a single list will unsubscribe from all lists and add to your GOO list.

                    [How to manage your Global Opt Out list (GOO)](https://support.transmitsms.com/support/solutions/articles/44001940660-how-to-manage-your-global-opt-out-list-goo-)

                    '
                  example: 12345
                msisdn:
                  type: integer
                  description: Mobile number of contact being opted out. Number must be defined in E.164 international format.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  list_ids:
                    type: array
                    description: One or more list ID's that contact was opted out of.
                    items:
                      type: integer
                    example:
                    - 123
                    - 456
                    - 789
                  error:
                    type: object
                    description: Error messages related to this call.
                    properties:
                      CODE:
                        type: string
                        description: Error code.
                      HEADER:
                        type: integer
                        description: HTTP header.
                      DESCRIPTION:
                        type: string
                        description: Description of the error.
                    example:
                      CODE: NOT_FOUND
                      HEADER: 400
                      DESCRIPTION: Contact with such mobile does not exist in this list.
              example:
                list_ids:
                - 4214121
                error:
                  code: SUCCESS
                  description: OK
            text/plain:
              schema:
                type: string
              example: "<?xml version=\"1.0\"?>\n<response>\n    <list_ids>\n        <item>4214121</item>\n    </list_ids>\n    <error>\n        <code>SUCCESS</code>\n        <description>OK</description>\n    </error>\n</response>"
  /add-contacts-bulk-progress.json:
    post:
      tags:
      - Contacts & Lists
      summary: Check Progress Of Import
      description: For large lists in excess of 50,000 contacts, it can take some time to process. This request will let you see the progress of the import.
      security:
      - basicAuth: []
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - list_id
              properties:
                list_id:
                  type: integer
                  description: ID of the list to be checked. This ID is the numerical reference to the list you uploaded the file to.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  list_id:
                    type: integer
                    description: ID of the list being checked
                  status:
                    type: string
                    description: Status of upload
                    enum:
                    - completed
                    - in progress
                    - failed
                  importlength:
                    type: integer
                    description: Total number of records in file. This count will include invalid numbers.
                  completed:
                    type: integer
                    description: Number of contacts processed. This gives us an update of all numbers processed, should be equal to importlength when complete.
                  duplicates:
                    type: integer
                    description: Number of duplicate contacts excluded from import. Any number that matches an existing contact on the list will not be imported. Only the first record imported is kept.
                  skipped:
                    type: integer
                    description: Number of rows in the file skipped. This can be caused by blank rows, invalid numbers, or rows with a blank record in the mobile column.
                  optout:
                    type: integer
                    description: Number of contacts that were already opted out.
                  imported:
                    type: integer
                    description: Number of contacts successfully imported.
              example:
                list_id: 4214121
                status: completed
                importlength: 2
                completed: 2
                duplicates: 0
                skipped: 0
                optout: 0
                imported: 2
                error:
                  code: SUCCESS
                  description: OK
            text/plain:
              schema:
                type: string
              example: "<?xml version=\"1.0\"?>\n<response>\n    <list_id>4214121</list_id>\n    <status>completed</status>\n    <importlength>2</importlength>\n    <completed>2</completed>\n    <duplicates>0</duplicates>\n    <skipped>0</skipped>\n    <optout>0</optout>\n    <imported>2</imported>\n    <error>\n        <code>SUCCESS</code>\n        <description>OK</description>\n    </error>\n</response>"
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: 'Use the `Authorization` header with the value `Basic {base64(api_key:api_secret)}`.

        - `api_key`: Your API key

        - `api_secret`: Your API secret

        '