openapi: 3.2.0
info:
  title: Contacts Batch Batch API
  version: '1'
  description: Contacts API v1
  contact:
    name: 8x8 Inc
    url: https://cpaas.8x8.com
    email: cpaas-support@8x8.com
  termsOfService: https://cpaas.8x8.com/sg/terms-and-conditions/
servers:
- url: https://contacts.8x8.com
  description: Asia-Pacific region
- url: https://contacts.us.8x8.com
  description: North America region
- url: https://contacts.8x8.uk
  description: Europe region
- url: https://contacts.8x8.id
  description: Indonesia region
security:
- apiKey: []
tags:
- name: Batch API
paths:
  /api/v1/accounts/{accountId}/contacts/batches/createContacts:
    parameters:
    - $ref: '#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/parameters/0'
    post:
      summary: Batch create contacts
      operationId: batch-upload-contacts
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/batch-upload-job'
        '400':
          $ref: '#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/get/responses/400'
      description: Batch create contacts using file. The file can be either CSV or Excel. The CSV file can contain a header row (the mapping of the columns will be automatic in this case), or not. For files without a header, the `fileColumns` property should be specified for a columns mapping.
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/batch-upload-contacts'
            examples:
              Upload a csv file with header and add contacts to groups:
                value:
                  file: {}
                  groups: 11566,88996
                  fileHasHeader: true
              Upload a file:
                value:
                  file: {}
              Upload a csv file without a header with specified columns:
                value:
                  file: {}
                  fileHasHeader: false
                  fileColumns: msisdn, firstName, lastName
      tags:
      - Batch API
  /api/v1/accounts/{accountId}/contacts/batches/deleteContacts:
    parameters:
    - $ref: '#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/parameters/0'
    post:
      summary: Batch delete contacts
      operationId: batch-delete-contacts
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/batch-job'
        '400':
          $ref: '#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/get/responses/400'
      description: 'Use this endpoint to delete multiple/all contacts in batch. Provide `ids` or `msisdns` to remove specific contacts, or set `"all": true` to delete all contacts in your account.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/batch-delete-contacts'
            examples:
              Specify contacts to delete:
                value:
                  ids:
                  - 41764539
                  - 41764538
                  msisdns:
                  - '+6512345678'
                  - '6523456789'
              Specify only contacts ids to delete:
                value:
                  ids:
                  - 41764539
                  - 41764538
              Specify only msisdns to delete:
                value:
                  msisdns:
                  - '+6512345678'
                  - '6523456789'
              Delete all contacts:
                value:
                  all: true
      tags:
      - Batch API
  /api/v1/accounts/{accountId}/groups/batches/copyContacts:
    parameters:
    - $ref: '#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/parameters/0'
    post:
      summary: Copy contacts between groups
      operationId: batch-copy-contacts
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/batch-job'
        '400':
          $ref: '#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/get/responses/400'
      parameters:
      - schema:
          type: integer
        in: query
        name: from
        description: Identifier of the source group
        required: true
      - schema:
          type: integer
        in: query
        name: to
        description: Identifier of the destination group
        required: true
      description: Copy contacts from ony group to another one.
      tags:
      - Batch API
  /api/v1/accounts/{accountId}/groups/batches/moveContacts:
    parameters:
    - $ref: '#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/parameters/0'
    post:
      summary: Move contacts between groups
      operationId: batch-move-contacts
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/batch-job'
        '400':
          $ref: '#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/get/responses/400'
      description: Move contacts from one group to another one. This operation will delete contacts in the original group.
      parameters:
      - schema:
          type: integer
        in: query
        name: from
        description: Identifier of the source group
        required: true
      - schema:
          type: integer
        in: query
        name: to
        description: Identifier of the destination group
        required: true
      tags:
      - Batch API
  /api/v1/accounts/{accountId}/groups/batches/deleteGroups:
    parameters:
    - $ref: '#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/parameters/0'
    post:
      summary: Batch delete groups
      operationId: batch-delete-groups
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/batch-job'
        '400':
          $ref: '#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/get/responses/400'
      description: Batch delete groups
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/batch-delete-groups'
      tags:
      - Batch API
  /api/v1/accounts/{accountId}/batches/{batchId}:
    parameters:
    - $ref: '#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/parameters/0'
    - schema:
        type: string
        format: uuid
      name: batchId
      in: path
      required: true
      description: Batch Id
    get:
      summary: Get batch information by id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/batch-job'
        '404':
          description: The entity doesn't exist
          content:
            application/json:
              schema:
                $ref: '#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/post/responses/409/content/application~1json/schema'
              example:
                code: 4018
                message: Invalid jobId
                errorId: aa400d4b-fffe-ea11-8277-00155d4ff7ed
                timestamp: '2020-09-25T07:18:22.78Z'
      operationId: get-batch-by-id
      description: Get batch information by id
      tags:
      - Batch API
  /api/v1/accounts/{accountId}/batches:
    parameters:
    - $ref: '#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/parameters/0'
    get:
      summary: Get batch job list
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/batch-job-list'
        '400':
          $ref: '#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/get/responses/400'
      operationId: get-batch-job-list
      description: Get batch job list
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - schema:
          type: string
          enum:
          - createContacts
          - deleteContacts
          - copyContacts
          - moveContacts
          - deleteGroups
        in: query
        name: type
        description: Use this parameter to filter by batch type
      tags:
      - Batch API
components:
  schemas:
    batch-status:
      type: string
      title: Batch Status
      enum:
      - queued
      - inProgress
      - failed
      - completed
      - stopped
      - timeout
      description: The status of the batch job
    batch-upload-job:
      description: Batch upload contacts job information
      type: object
      x-examples:
        example-1:
          fileName: 1_Contacts.csv
          fileType: csv
          fileLocation: https://8x8.com/contacts/1_Contacts.csv
          id: 1da76ae9-5f8d-40c1-ba71-ae7b00abb23e
          type: createContacts
          status: queued
          createdAt: '2022-04-18T10:25:07.95Z'
      properties:
        fileName:
          type: string
          description: Name of the uploaded file
        fileType:
          type: string
          description: Type of the uploaded file
          enum:
          - csv
          - xls
        fileLocation:
          type: string
          description: URL of the uploaded file
        id:
          type: string
          description: Batch id. Use this value to request batch status.
          format: uuid
        type:
          $ref: '#/components/schemas/batch-type'
        status:
          $ref: '#/components/schemas/batch-status'
        createdAt:
          type: string
          minLength: 1
          description: Created time
      title: Batch upload contacts job
    batch-delete-contacts:
      description: Batch delete contacts
      type: object
      x-examples:
        Specify contacts to delete:
          ids:
          - 41764539
          - 41764538
          msisdns:
          - '+6512345678'
          - '6523456789'
        Delete all contacts in your account:
          all: true
      properties:
        ids:
          type: array
          items:
            type: integer
        msisdns:
          type: array
          items:
            type: string
        all:
          type: boolean
          description: Set true to delete all contacts in your account
      title: Batch delete contacts
    batch-type:
      type: string
      title: Batch type
      description: The type of the batch job
      enum:
      - createContacts
      - deleteContacts
      - copyContacts
      - moveContacts
      - deleteGroups
    batch-upload-contacts:
      title: batch-upload-contacts
      type: object
      properties:
        file:
          type: object
          description: 'Binary content of the file.


            **The file size is limited to 30 Mb.**'
        groups:
          type: string
          description: "Comma-separated list of group id (integer) to add contacts to. \n\n**You can add contacts to 10 groups max.**"
          example: 11566,88996
        fileHasHeader:
          type: boolean
          default: true
          description: "Set this property to `true` if provided file has a header row. \n\nThe header row will be parsed automatically, you don't need to provide a list of columns in this case.\n\nDefault value is `true`"
        fileColumns:
          type: string
          description: "Comma-separated list of columns. \n\nThis field is **mandatory** is `fileHasHeader` is `false`"
          example: msisdn, firstName, lastName
      required:
      - file
    batch-delete-groups:
      description: ''
      type: object
      x-examples:
        example-1:
          ids:
          - 6806
          - 6780
          deleteContacts: true
      properties:
        ids:
          type: array
          description: Identifiers of groups to delete
          items:
            type: integer
        deleteContacts:
          type: boolean
          description: Set to `true` to delete contacts in these groups
      required:
      - ids
      - deleteContacts
    batch-job:
      description: Batch job information
      type: object
      x-examples:
        example-1:
          id: dc6b1743-391b-4a72-bcea-ae7c0062bbb7
          type: deleteContacts
          status: queued
          createdAt: '2022-04-19T05:59:28.61Z'
      title: Batch job info
      properties:
        id:
          type: string
          format: uuid
          description: 'Batch job id

            '
        type:
          $ref: '#/components/schemas/batch-type'
        status:
          $ref: '#/components/schemas/batch-status'
        createdAt:
          type: string
          description: Job created date and time
    batch-job-list:
      description: ''
      type: object
      x-examples:
        example-1:
          items:
          - id: 576171ed-ab50-427d-a1c8-ae7c0079fdc1
            type: deleteContacts
            status: completed
            createdAt: '2022-04-19T07:24:09.28Z'
          - fileName: 1_Contacts-without-Errors-with-header-with-duplicates.csv
            fileType: csv
            fileLocation: https://8x8.com/1_Contacts.csv
            invalidFileLocation: https://8x8.com/invalid_contacts.csv
            totalRows: 12
            errorRows: 6
            duplicatedRows: 5
            insertedRows: 2
            contactGroups: 0
            id: 1da76ae9-5f8d-40c1-ba71-ae7b00abb23e
            type: createContacts
            status: completed
            createdAt: '2022-04-18T10:25:07.78Z'
          - id: 576171ed-ab50-427d-a1c8-ae7c0079fdc3
            type: moveContacts
            status: completed
            createdAt: '2022-04-19T07:33:09.28Z'
          page: 1
          totalPages: 1
          totalCount: 3
          totalFiltered: 3
          hasPreviousPage: false
          hasNextPage: false
      properties:
        items:
          type: array
          uniqueItems: true
          minItems: 1
          items:
            anyOf:
            - $ref: '#/components/schemas/batch-job'
            - $ref: '#/components/schemas/batch-upload-job'
        page:
          type: number
        totalPages:
          type: number
        totalCount:
          type: number
        totalFiltered:
          type: number
        hasPreviousPage:
          type: boolean
        hasNextPage:
          type: boolean
      title: ''
  parameters:
    limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 500
        default: 20
        format: int32
      description: Number of items to include in the response
    offset:
      name: offset
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        format: int32
      description: Page offset. Setting limit to 10 and offset to 0 returns the first 10 items. Increment offset to retrieve more items.
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: '* 8x8 SMS API accepts an **ApiKey Bearer Token** authentication method.


        * You can generate  tokens from your customer portal  [https://connect.8x8.com/](https://connect.8x8.com/)


        * You need to include the following header in your requests: `Authorization: Bearer {apiKey}`


        > **Note**: Replace the `{apiKey}` placeholder with the key generated from the customer portal.

        ---

        If you haven''t created your account yet, please go to 8x8 website [https://connect.8x8.com](https://connect.8x8.com) to sign up.

        '
x-readme:
  explorer-enabled: true
  proxy-enabled: true