Everbridge Contact Builder APIs API

openapi: 3.2.0
info:
  title: Communications Contact Builder APIs API
  description: Unified Communications APIs
  version: '1.0'
servers:
- url: https://api.everbridge.net/managerapps/communications/v1
tags:
- name: Contact Builder APIs
paths:
  /contact-builder/from-csv:
    post:
      tags:
      - Contact Builder APIs
      operationId: contactsFromCsv
      summary: Upload a CSV of External IDs and get parsing results
      description: Accepts a CSV file upload and returns details about rows processed, unique external IDs, and any errors.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                Filedata:
                  type: string
                  format: binary
                  description: CSV file to upload
              required:
              - Filedata
      responses:
        '200':
          description: CSV processed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactsFromCsvResult'
        '400':
          description: Missing or invalid file
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
      security:
      - API_Authorizer: []
      x-amazon-apigateway-integration:
        type: http_proxy
        connectionId: 11ofco
        httpMethod: POST
        uri: https://prod-us-us-east-1-0-os-nginx.ue1-0.prod-us.prod.us-east-1.evbg.io/cem-comms/contact-builder/from-csv
        responses:
          default:
            statusCode: '200'
        passthroughBehavior: when_no_match
        connectionType: VPC_LINK
  /contact-builder:
    post:
      tags:
      - Contact Builder APIs
      operationId: startNewSession
      summary: Start a New Session
      description: Start a new Contact Builder session. Data may be provided to initialize the session's buckets but is not required. This data will be processed asynchronously.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSessionRequest'
            examples:
              Starting a new session without seeding data:
                summary: Starting a new session without seeding data
                value:
                  data: {}
              Starting a new session with seeding data:
                summary: Starting a new session with seeding data
                value:
                  data:
                    individual:
                      contacts:
                      - type: Id
                        contactId: 1234567890
                      - type: ExternalId
                        externalId: jsmith1
        required: true
      responses:
        '201':
          description: The session has been started.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSessionResponse'
              examples:
                Successful Start of the Session:
                  summary: Successful Start of the Session
                  value:
                    sessionId: 73ef9c42-df40-41c8-9b2d-6618ed5c31c1
                    expiration: '2024-07-03T20:06:09.734385Z'
                    buckets:
                    - individual
                    - group
                    - rule
                    - query
                    - exclusion
                    - alert
                    - thread
        '400':
          description: The request failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Single validation error:
                  summary: Single validation error
                  value:
                    type: /client-error/invalid-parameter
                    title: Bad Request
                    status: 400
                    detail: 'The "Field Name #1" field must not be empty.'
                    instance: request-id
                Multiple validation errors:
                  summary: Multiple validation errors
                  value:
                    type: /client-error/invalid-parameter
                    title: Bad Request
                    status: 400
                    detail: 'The "title" field must not be empty.

                      The "eventType" field must not be empty.

                      The "Field Name #1" field must not be empty.'
                    instance: request-id
        '401':
          description: The token provided does not have permission to access this API.
        '500':
          description: An internal error has occurred. This may not always return a response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                An internal server error has occurred:
                  summary: An internal server error has occurred
                  value:
                    type: about:blank
                    title: Internal Server Error
                    status: 500
                    detail: null
                    instance: request-id
      security:
      - API_Authorizer: []
      x-amazon-apigateway-integration:
        type: http_proxy
        connectionId: 11ofco
        httpMethod: POST
        uri: https://prod-us-us-east-1-0-os-nginx.ue1-0.prod-us.prod.us-east-1.evbg.io/cem-comms/contact-builder
        responses:
          default:
            statusCode: '201'
        passthroughBehavior: when_no_match
        connectionType: VPC_LINK
  /contact-builder/{sessionId}:
    get:
      tags:
      - Contact Builder APIs
      operationId: getSession
      summary: Retrieve the Current Session
      description: Retrieve metadata regarding the current session.
      parameters:
      - in: path
        name: sessionId
        required: true
        schema:
          type: string
        description: The unique identifier for the session to be modified.
      responses:
        '200':
          description: Metadata regarding the session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSession'
              examples:
                Session Metadata:
                  summary: Successful Start of the Session
                  value:
                    sessionId: 73ef9c42-df40-41c8-9b2d-6618ed5c31c1
                    created: '2024-07-03T19:06:09.734385Z'
                    expiration: '2024-07-03T20:06:09.734385Z'
                    buckets:
                    - individual
                    - group
                    - rule
                    - query
                    - exclusion
                    - alert
                    - thread
                    status: IDLE
        '401':
          description: The token provided does not have permission to access this API.
        '404':
          description: The session does not exist.
        '500':
          description: An internal error has occurred. This may not always return a response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                An internal server error has occurred:
                  summary: An internal server error has occurred
                  value:
                    type: about:blank
                    title: Internal Server Error
                    status: 500
                    detail: null
                    instance: request-id
      security:
      - API_Authorizer: []
      x-amazon-apigateway-integration:
        type: http_proxy
        connectionId: 11ofco
        httpMethod: GET
        uri: https://prod-us-us-east-1-0-os-nginx.ue1-0.prod-us.prod.us-east-1.evbg.io/cem-comms/contact-builder/{sessionId}
        responses:
          default:
            statusCode: '200'
        requestParameters:
          integration.request.path.sessionId: method.request.path.sessionId
        passthroughBehavior: when_no_match
        connectionType: VPC_LINK
    put:
      tags:
      - Contact Builder APIs
      operationId: modifySession
      summary: Modify an Existing Session
      description: Add or remove data from one or more buckets in an existing Contact Builder session. Providing at least one data item is required. This data will be processed asynchronously.
      parameters:
      - in: path
        name: sessionId
        required: true
        schema:
          type: string
        description: The unique identifier for the session to be modified.
      - in: query
        name: remove
        schema:
          type: boolean
        description: '*Deprecated:* Please use `operation` instead.


          Flag to indicate if the data should be removed from the session instead of the default behavior of adding it.'
        deprecated: true
      - in: query
        name: operation
        schema:
          type: string
          enum:
          - ADD
          - REMOVE
          - CLEAR
        description: Flag to indicate the type of modification to be performed on the session. `ADD` will add the provided data to the session, `REMOVE` will remove the provided data from the session, and `CLEAR` will remove all data from the specified buckets in the session. If not provided, the default operation is `ADD`.
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/ModificationRequest'
              - $ref: '#/components/schemas/ClearBucketsRequest'
            examples:
              Add or remove data from buckets in a session:
                summary: Add or remove data from buckets in a session
                value:
                  data:
                    individual:
                      contacts:
                      - type: Id
                        contactId: 1234567890
                      - type: ExternalId
                        externalId: jsmith1
              Clear all data from the specified buckets in a session:
                summary: Clear all data from the specified buckets in a session.
                value:
                  buckets:
                  - individual
                  - group
        required: true
      responses:
        '202':
          description: The data has been accepted and has been enqueued to be processed asynchronously. Does not return a response body.
        '400':
          description: The request failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Single validation error:
                  summary: Single validation error
                  value:
                    type: /client-error/invalid-parameter
                    title: Bad Request
                    status: 400
                    detail: 'The "Field Name #1" field must not be empty.'
                    instance: request-id
                Multiple validation errors:
                  summary: Multiple validation errors
                  value:
                    type: /client-error/invalid-parameter
                    title: Bad Request
                    status: 400
                    detail: 'The "title" field must not be empty.

                      The "eventType" field must not be empty.

                      The "Field Name #1" field must not be empty.'
                    instance: request-id
        '401':
          description: The token provided does not have permission to access this API.
        '404':
          description: The session does not exist.
        '409':
          description: The session has been completed or is in the process of being completed. No further modifications can be made to the session.
        '500':
          description: An internal error has occurred. This may not always return a response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                An internal server error has occurred:
                  summary: An internal server error has occurred
                  value:
                    type: about:blank
                    title: Internal Server Error
                    status: 500
                    detail: null
                    instance: request-id
      security:
      - API_Authorizer: []
      x-amazon-apigateway-integration:
        type: http_proxy
        connectionId: 11ofco
        httpMethod: PUT
        uri: https://prod-us-us-east-1-0-os-nginx.ue1-0.prod-us.prod.us-east-1.evbg.io/cem-comms/contact-builder/{sessionId}
        responses:
          default:
            statusCode: '202'
        requestParameters:
          integration.request.path.sessionId: method.request.path.sessionId
        passthroughBehavior: when_no_match
        connectionType: VPC_LINK
  /contact-builder/{sessionId}/query:
    get:
      tags:
      - Contact Builder APIs
      operationId: getQuery
      summary: Retrieve the Queries for a Session
      description: Retrieves the CEM Results `SemanticQuery` objects based on the modifications made to the session in addition to any result IDs that were added to the session.
      parameters:
      - in: path
        name: sessionId
        required: true
        schema:
          type: string
        description: The unique identifier for the session.
      responses:
        '200':
          description: The queries have been generated and returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'
              examples:
                Successful retrieval of queries:
                  summary: Successful retrieval of queries
                  value:
                    individual:
                    - type: ResultSetCommand
                      command:
                        type: SemanticQuery
                        identified:
                        - '123'
                        - '456'
                    - type: ResultSetId
                      id: evbg+result:contact:my-contacts:1697471720114
                    group: []
                    rule: []
                    query: []
                    exclusion: []
                    alert: []
                    thread: []
        '401':
          description: The token provided does not have permission to access this API.
        '404':
          description: The session does not exist.
        '409':
          description: The session has been completed or is in the process of being completed. Once the session is completed, the queries are no longer available.
        '500':
          description: An internal error has occurred. This may not always return a response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                An internal server error has occurred:
                  summary: An internal server error has occurred
                  value:
                    type: about:blank
                    title: Internal Server Error
                    status: 500
                    detail: null
                    instance: request-id
      security:
      - API_Authorizer: []
      x-amazon-apigateway-integration:
        type: http_proxy
        connectionId: 11ofco
        httpMethod: GET
        uri: https://prod-us-us-east-1-0-os-nginx.ue1-0.prod-us.prod.us-east-1.evbg.io/cem-comms/contact-builder/{sessionId}/query
        responses:
          default:
            statusCode: '200'
        requestParameters:
          integration.request.path.sessionId: method.request.path.sessionId
        passthroughBehavior: when_no_match
        connectionType: VPC_LINK
  /contact-builder/{sessionId}/summary:
    get:
      tags:
      - Contact Builder APIs
      operationId: getSummary
      summary: Retrieve the Summary of Contact Totals for a Session
      description: Retrieves the total number of contacts across all buckets as well as the total number of contacts within each bucket.
      parameters:
      - in: path
        name: sessionId
        required: true
        schema:
          type: string
        description: The unique identifier for the session.
      responses:
        '200':
          description: The summary was calculated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SummaryCounts'
              examples:
                Successful retrieval of the summary:
                  summary: Successful retrieval of the summary
                  value:
                    total: 3
                    buckets:
                      individual: 2
                      group: 1
        '401':
          description: The token provided does not have permission to access this API.
        '404':
          description: The session does not exist.
        '409':
          description: The session has been completed or is in the process of being completed. Once the session is completed, the summary is no longer available.
        '500':
          description: An internal error has occurred. This may not always return a response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                An internal server error has occurred:
                  summary: An internal server error has occurred
                  value:
                    type: about:blank
                    title: Internal Server Error
                    status: 500
                    detail: null
                    instance: request-id
      security:
      - API_Authorizer: []
      x-amazon-apigateway-integration:
        type: http_proxy
        connectionId: 11ofco
        httpMethod: GET
        uri: https://prod-us-us-east-1-0-os-nginx.ue1-0.prod-us.prod.us-east-1.evbg.io/cem-comms/contact-builder/{sessionId}/summary
        responses:
          default:
            statusCode: '200'
        requestParameters:
          integration.request.path.sessionId: method.request.path.sessionId
        passthroughBehavior: when_no_match
        connectionType: VPC_LINK
  /contact-builder/{sessionId}/preview:
    get:
      tags:
      - Contact Builder APIs
      operationId: getContactPreview
      summary: Retrieve the Individual Contacts for a Session
      description: Retrieves a paginated set of the contacts that were added to a session. This endpoint will return a `409 Conflict` status code if the session has exceeded 10,000 contacts.
      parameters:
      - in: path
        name: sessionId
        required: true
        schema:
          type: string
        description: The unique identifier for the session.
      - in: query
        name: sortBy
        schema:
          type: string
          enum:
          - FIRSTNAME
          - MIDDLEINITIAL
          - LASTNAME
          - EMAIL
          - COUNTRY
          - EXTERNALID
          default: LASTNAME
        description: Field to sort the contact data by.
      - in: query
        name: sortDirection
        schema:
          type: string
          enum:
          - ASC
          - ASCENDING
          - DESC
          - DESCENDING
          default: ASC
        description: Direction to sort the contact data by. `ASC` is equivalent to `ASCENDING` and `DESC` is equivalent to `DESCENDING`.
      - in: query
        name: direction
        schema:
          type: string
          enum:
          - ASC
          - ASCENDING
          - DESC
          - DESCENDING
          default: ASC
        description: See `sortDirection`. This parameter is maintained for backwards compatibility and may be removed in a future release. If both `sortDirection` and `direction` are provided, `sortDirection` takes precedence.
      - in: query
        name: pageSize
        schema:
          type: number
          minimum: 1
          maximum: 250
          default: 100
        description: The number of contacts to return in a single page.
      - in: query
        name: pageNumber
        schema:
          type: number
          minimum: 1
          default: 1
        description: The page number to request.
      - in: query
        name: includeExcludedContacts
        schema:
          type: boolean
          default: false
        allowEmptyValue: true
        description: If `true`, the API will return the excluded contacts in the results. If `false`, the API will filter out the excluded contacts from the results.
      - in: query
        name: bucket
        schema:
          type: array
          items:
            type: string
            enum:
            - INDIVIDUAL
            - GROUP
            - RULE
            - QUERY
            - EXCLUSION
            - ALERT
            - THREAD
        description: The buckets to consider when determining the paginated set. If not provided, all buckets will be considered.
        style: form
        explode: true
      - in: query
        name: name
        schema:
          type: string
        description: Filter the results by the contact's first name, middle initial, and last name.
      - in: query
        name: group
        schema:
          type: array
          items:
            type: integer
            format: int64
        description: Filter the results by whether the contacts belong to the specified contact group IDs.
      - in: query
        name: rule
        schema:
          type: array
          items:
            type: integer
            format: int64
        description: Filter the results by any contact rules (filters) that match on the contact.
      - in: query
        name: resultSet
        schema:
          type: array
          items:
            type: string
        description: Filter the results by whether the contacts are included in the specified result set ID.
      responses:
        '200':
          description: A page of contact data was returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactBuilderPreviewResponse'
              examples:
                Successful retrieval of contacts:
                  summary: Successful retrieval of contacts
                  value:
                    data:
                    - id: 867381530896572
                      firstName: Colton
                      middleInitial: B
                      lastName: Aaron
                      externalId: eb1-207-1037
                      recordTypeId: 300308408303662
                      recordTypeName: Family
                      registerEmail: null
                      country: US
                      addresses:
                      - streetAddress: 999 Kracht Blvd
                        city: San Diego
                        state: CA
                        postalCode: '26532'
                        country: US
                        locationType: Static
                        locationName: Ridell Office
                      - streetAddress: 911 Bellettiere Rd
                        city: San Diego
                        state: CA
                        postalCode: '97989'
                        country: US
                        locationType: Static
                        locationName: Burian Office
                      createdName: John Everbridge
                      lastModifiedDate: '2025-03-12T07:37:22.525Z'
                    - id: 867381530973026
                      firstName: Bobbie
                      middleInitial: null
                      lastName: Barajas
                      externalId: eb1-480-4060
                      recordTypeId: 1328214341321654
                      recordTypeName: Employee
                      registerEmail: null
                      country: US
                      addresses:
                      - streetAddress: 529 N Sementilli Way
                        city: Detroit
                        state: MI
                        postalCode: '95541'
                        country: US
                        locationType: Static
                        locationName: Scheidler Office
                      createdName: John Everbridge
                      lastModifiedDate: '2024-01-11T07:02:46.27Z'
                    - id: 867381531046170
                      firstName: Eugene
                      middleInitial: null
                      lastName: Catalan
                      externalId: eb1-611-1651
                      recordTypeId: 1328214341321654
                      recordTypeName: Employee
                      registerEmail: null
                      country: US
                      addresses:
                      - streetAddress: 521 E Izatt
                        city: Glasgow
                        state: null
                        postalCode: '48055'
                        country: GB
                        locationType: Static
                        locationName: Fenoglio Office
                      - streetAddress: 846 E Rowen
                        city: Glasgow
                        state: null
                        postalCode: '55610'
                        country: GB
                        locationType: Static
                        locationName: Tonrey Office
                      - streetAddress: 618 N Alas Rd
                        city: Glasgow
                        state: null
                        postalCode: '70239'
                        country: GB
                        locationType: Static
                        locationName: Irizarri Office
                      createdName: John Everbridge
                      lastModifiedDate: '2024-01-11T07:04:10.279Z'
                    - id: 867381531063337
                      firstName: Xochitl
                      middleInitial: null
                      lastName: Zuniga
                      externalId: eb1-1368-535
                      recordTypeId: 1328214341321654
                      recordTypeName: Employee
                      registerEmail: null
                      country: US
                      addresses:
                      - streetAddress: 926 Haeuser
                        city: Dusseldorf
                        state: null
                        postalCode: '06127'
                        country: DE
                        locationType: Static
                        locationName: Finklestein Office
                      - streetAddress: 262 N Bronder Way
                        city: Dusseldorf
                        state: null
                        postalCode: 09458
                        country: DE
                        locationType: Static
                        locationName: Peaker Office
                      createdName: John Everbridge
                      lastModifiedDate: '2021-03-16T20:49:28.753Z'
                    pages:
                      currentPage: 1
                      pageSize: 100
                      pageCount: 4
                      totalPages: 1
                      maxSize: 250
                      totalCount: 4
        '401':
          description: The token provided does not have permission to access this API.
        '404':
          description: The session does not exist.
        '409':
          description: The session has been completed, is in the process of being completed, or the set of contacts in the session exceeds 10,000.
        '500':
          description: An internal error has occurred. This may not always return a response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                An internal server error has occurred:
                  summary: An internal server error has occurred
                  value:
                    type: about:blank
                    title: Internal Server Error
                    status: 500
                    detail: null
                    instance: request-id
      security:
      - API_Authorizer: []
      x-amazon-apigateway-integration:
        type: http_proxy
        connectionId: 11ofco
        httpMethod: GET
        uri: https://prod-us-us-east-1-0-os-nginx.ue1-0.prod-us.prod.us-east-1.evbg.io/cem-comms/contact-builder/{sessionId}/preview
        responses:
          default:
            statusCode: '200'
        requestParameters:
          integration.request.path.sessionId: method.request.path.sessionId
        passthroughBehavior: when_no_match
        connectionType: VPC_LINK
  /contact-builder/{sessionId}/result:
    post:
      tags:
      - Contact Builder APIs
      operationId: endSession
      summary: End Session
      description: End the session. This will begin generating and creating Result Sets. The CEM Results IDs, sorted by bucket, are returned upon successful completion.
      parameters:
      - in: path
        name: sessionId
        required: true
        schema:
          type: string
        description: The unique identifier for the session.
      responses:
        '201':
          description: The session has ended and the result sets have been created. The result set IDs will be available from this endpoint for up to ten minutes after the session has completed. After ten minutes, the session and its results will no longer be available from this endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultResponse'
              examples:
                Successful End of the Session:
                  summary: Successful End of the Session
                  value:
                    individual:
                    - evbg+result:contact:my-contacts:1697471720114
                    group: []
                    rule: []
                    query: []
                    exclusion: []
                    alert: []
                    thread: []
        '202':
          description: The process of ending the session is taking longer than expected. The process will continue in the background; please try the request again to retrieve the results when they are ready.
        '400':
          description: The request failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Single validation error:
                  summary: Single validation error
                  value:
                    type: /client-error/invalid-parameter
                    title: Bad Request
                    status: 400
                    detail: 'The "Field Name #1" field must not be empty.'
                    instance: request-id
                Multiple validation errors:
                  summary: Multiple validation errors
                  value:
                    type: /client-error/invalid-parameter
                    title: Bad Request
                    status: 400
                    detail: 'The "title" field must not be empty.

                      The "eventType" field must not be empty.

                      The "Field Name #1" field must not be empty.'
                    instance: request-id
        '401':
          description: The token provided does not have permission to access this API.
        '404':
          description: The session does not exist.
        '500':
          description: An internal error has occurred. This may not always return a response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                An internal server error has occurred:
                  summary: An internal server error has occurred
                  value:
                    type: about:blank
                    title: Internal Server Error
                    status: 500
                    detail: null
                    instance: request-id
      security:
      - API_Authorizer: []
 

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