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: [] 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/{sessionId}/result responses: default: statusCode: '201' requestParameters: integration.request.path.sessionId: method.request.path.sessionId passthroughBehavior: when_no_match connectionType: VPC_LINK components: schemas: ContactsFromCsvResult: type: object properties: success: type: boolean resultCode: type: integer message: type: - string - 'null' processedCSVRecordCount: type: integer externalIdCount: type: integer contactCount: type: integer contacts: type: array items: $ref: '#/components/schemas/Contact' additionalInfos: type: - array - 'null' items: type: string required: - success - resultCode - processedCSVRecordCount - externalIdCount - contactCount - contacts QueryResponseBucket: type: array items: anyOf: - $ref: '#/components/schemas/QueryResponseItemResultSetCommand' - $ref: '#/components/schemas/QueryResponseItemResultSetId' RuleBucketData: type: object description: Data to be stored in a bucket that supports contact rules (filters). properties: rules: type: array description: A list of contact rules (filters) to be included in the bucket maxItems: 10 items: $ref: '#/components/schemas/ApiRuleId' SummaryCounts: type: object description: A summary of the number of contacts within each bucket in a session. A bucket may not be present if it has no contacts. required: - total - buckets properties: total: type: integer format: int64 description: The total number of contacts across all buckets in the session. The `exclusion` bucket is subtracted from the total. buckets: type: object description: A map of bucket names to the number of contacts in each bucket. properties: individual: type: integer format: int64 description: The number of contacts in the "individual" bucket. group: type: integer format: int64 description: The number of contacts in the "group" bucket. rule: type: integer format: int64 description: The number of contacts in the "rule" bucket. query: type: integer format: int64 description: The number of contacts in the "query" bucket. exclusion: type: integer format: int64 description: The number of contacts in the "exclusion" bucket. alert: type: integer format: int64 description: The number of contacts in the "alert" bucket. thread: type: integer format: int64 description: The number of contacts in the "thread" bucket. subsets: $ref: '#/components/schemas/SummarySubsetCounts' public: type: object description: The counts of public users within the session's buckets. properties: provisionalCount: type: integer format: int64 description: A provisional count of the total number public users that are a part of this session. The actual number may be lower than this number when the session is ended. subscribedToIds: type: array description: The aggregated list of known subscription IDs that are included in the session. items: type: string buckets: type: object description: A map of bucket names to the number of public users in each bucket. properties: individual: $ref: '#/components/schemas/PublicBucketSummary' group: $ref: '#/components/schemas/PublicBucketSummary' rule: $ref: '#/components/schemas/PublicBucketSummary' query: $ref: '#/components/schemas/PublicBucketSummary' exclusion: $ref: '#/components/schemas/PublicBucketSummary' alert: $ref: '#/components/schemas/PublicBucketSummary' thread: $ref: '#/components/schemas/PublicBucketSummary' public: $ref: '#/components/schemas/PublicBucketSummary' subsets: $ref: '#/components/schemas/SummarySubsetCounts' Contact: type: object properties: id: type: integer format: int64 externalId: type: - string - 'null' firstName: type: string lastName: type: string middleInitial: type: - string - 'null' suffix: type: - string - 'null' required: - id - firstName - lastName ContactBuilderPreviewResponse: allOf: - $ref: '#/components/schemas/BaseApiPaginatedResponse' - type: object description: A page of individual contacts that were added to the session. properties: data: type: array items: type: object description: A contact added to the current session. properties: id: type: number format: int64 description: The contact's system identifier. firstName: type: string description: The contact's first or given name. middleInitial: type: string description: The contact's middle initial. lastName: type: string description: The contact's last or family name. externalId: type: string description: The contact's identifier as defined by the organization. recordTypeId: type: number format: int64 description: The system identifier for the contact record type that the contact is assigned to. recordTypeName: type: string description: The name of the contact record type that the contact is assigned to. registerEmail: type: string description: The email address that the contact used to register with Everbridge. country: type: string description: The country the contact is located in, represented as an ISO 3166-1 alpha-2 country code. addresses: type: array description: A list of the contact's addresses uploaded to Everbridge. items: properties: streetAddress: type: string description: The street address of the contact. city: type: string description: The city of the contact. state: type: string description: The state or province of the contact. postalCode: type: string description: The postal or ZIP code of the contact. country: type: string description: The country of the contact, represented as an ISO 3166-1 alpha-2 country code. locationType: type: string description: Describes the type of address. locationName: type: string description: The name of the location associated with the address. createdName: type: string description: The name of the user or system that created the contact. lastModifiedDate: type: string format: date-time description: The date and time when the contact was last modified, in ISO 8601 format. ApiQuerySemanticQuery: type: object description: Include a set of individual contacts by a CEM Results `SemanticQuery`. properties: type: type: string enum: - SemanticQuery description: Must be set to `SemanticQuery`. command: $ref: '#/components/schemas/SemanticQuery' required: - type - command ApiContactId: type: object description: Include an individual contact by their unique system ID. properties: type: type: string enum: - Id description: Must be set to `Id`. contactId: type: integer format: int64 description: The unique system ID of the contact. required: - type - contactId ApiGroupId: type: object description: Include a set of individual contacts by their membership in a contact group. properties: type: type: string enum: - Id description: Must be set to `Id`. groupId: type: integer format: int64 description: The unique system ID of the contact group. required: - type - groupId CreateSessionRequest: type: object description: Request body to start a new session. properties: data: $ref: '#/components/schemas/BucketData' threadSets: type: object description: A map of bucket names to result set IDs from a previous communication. By intersecting these result sets with the final results from the `thread` bucket, the service can recategorize results into the buckets they belonged to previously. properties: individual: type: array items: type: string description: Result set IDs representing the set of recipients added to a previous communication through the `individual` bucket. group: type: array items: type: string description: Result set IDs representing the set of recipients added to a previous communication through the `group` bucket. rule: type: array items: type: string description: Result set IDs representing the set of recipients added to a previous communication through the `rule` bucket. query: type: array items: type: string description: Result set IDs representing the set of recipients added to a previous communication through the `query` bucket. alert: type: array items: type: string description: Result set IDs representing the set of recipients added to a previous communication through the `alert` bucket. public: type: array items: type: string description: Result set IDs representing the set of recipients added to a previous communication through the `public` bucket. SemanticQuery: allOf: - $ref: '#/components/schemas/Command' description: A query use for generating a CEM Result built with semantic logic type: object properties: type: type: string description: The type of command to execute enum: - SemanticQuery inArea: $ref: '#/components/schemas/Geometry' starting: type: string format: date-time description: Optional start time for bounding the query. Affects some locations and travel itineraries. ending: type: string format: date-time description: Optional end time for bounding the query. Affects some locations and travel itineraries. ofTypeIds: type: array items: type: string description: A list of contact or asset type IDs to filter the results by. tagged: type: array items: type: string description: A list of tags to filter the results by. inPropertyIds: type: array items: type: string description: A list of property IDs to filter the results by. withProperties: type: array items: anyOf: - $ref: '#/components/schemas/CemResultsBooleanPropertyQuery' - $ref: '#/components/schemas/CemResultsNumberPropertyQuery' - $ref: '#/components/schemas/CemResultsStringPropertyQuery' description: A list of property IDs to filter the results by. named: type: array items: anyOf: - $ref: '#/components/schemas/CemResultsCompleteName' description: A list of names to filter the results by. identified: type: array items: type: string description: A list of identifiers to filter the results by. memberOfIds: type: array items: type: number description: A list of groups IDs to find members of. withLocationTypes: type: array items: anyOf: - $ref: '#/components/schemas/CemResultsStaticLocationType' - $ref: '#/components/schemas/CemResultsLastKnownLocationType' - $ref: '#/components/schemas/CemResultsExpectedLocationType' - $ref: '#/components/schemas/CemResultsTravelLocationType' description: A list of location types to filter the results by. ofRuleIds: type: array items: type: number description: A list of rules to filter the results by. isExpatriate: type: boolean description: If true, include expatriates in the results for contact result sets. isVip: type: boolean description: If true, include VIPs in the results for contact result sets. subscribedToIds: type: array items: type: string description: A list of public feed IDs to retrieve subscribers for. Only applicable to `publicuser` result sets. forZipCodes: type: array items: type: string description: A list of zipcodes to filter subscribers. Only applicable to `publicuser` result set. sendToAorSubscriptions: type: boolean description: If true, include org area-of-responsibility subscriptions. Only applicable to `publicuser` result set. QueryResponseItemResultSetId: type: object description: A CEM Results identifier that was previously added to this bucket. properties: type: type: string enum: - ResultSetId description: Must be set to `ResultSetId`. id: type: string description: The CEM Result identifier. example: evbg+result:contact:my-contacts:1697471720114 required: - type - id SummarySubsetCounts: type: object description: The counts of individual contact groups, rules (filters), and CEM Result Sets within each bucket. properties: individual: $ref: '#/components/schemas/SummarySubsetTypes' group: $ref: '#/components/schemas/SummarySubsetTypes' rule: $ref: '#/components/schemas/SummarySubsetTypes' query: $ref: '#/components/schemas/SummarySubsetTypes' exclusion: $ref: '#/components/schemas/SummarySubsetTypes' alert: $ref: '#/components/schemas/SummarySubsetTypes' thread: $ref: '#/components/schemas/SummarySubsetTypes' public: $ref: '#/components/schemas/SummarySubsetTypes' CemResultsStaticLocationType: type: object description: Specifies how to include contacts with static location types in CEM Results. required: - type properties: type: type: string description: Must be set to exactly `Static`. enum: - Static locationTypeIds: type: array description: A list of static location type IDs. items: type: number includeMissingLocationTypeId: type: boolean description: If true, include results that do not have a static location type. QueryResponseItemResultSetCommandRecipientsOf: type: object description: A `RecipientsOf` command for retrieving recipients directly from the notification report log. properties: type: type: string enum: - RecipientsOf description: Must be set to `RecipientsOf`. notificationId: type: number description: The ID of the notification to read the report log of. format: int64 confirmationStatuses: type: array description: The list of confirmation statuses to include in the results. If empty, then contacts with any confirmation status will be included. items: type: string enum: - Confirmed - Attempted - ConfirmedLate - Unreachable - Duplicate - Dismissed confirmedPathIds: type: - number - 'null' format: int64 description: Not currently used. required: - type - notificationId ClearBucketsRequest: type: object description: Request body to clear all data from the listed buckets. required: - buckets properties: buckets: type: array minItems: 1 description: The buckets to clear. At least one bucket must be supplied. items: type: string enum: - individual - group - rule - query - exclusion - alert - thread - public ModificationRequest: type: object description: Request body to modify an existing session. properties: data: $ref: '#/components/schemas/BucketData' required: - data ApiSession: type: object description: The current session metadata. properties: sessionId: type: string description: The unique identifier for the newly created session. example: 73ef9c42-df40-41c8-9b2d-6618ed5c31c1 created: type: string format: date-time description: The created time of the session in ISO 8601 format. example: '2024-07-03T20:06:09.734385Z' expiration: type: string format: date-time description: The expiration time of the session in ISO 8601 format. example: '2024-07-03T20:06:09.734385Z' buckets: type: array description: A list of buckets created in the session. items: type: string description: The unique identifier for each bucket created in the session. status: type: string description: 'The current status of the session. * `IDLE`: The session is idle and ready for additional modifications to its buckets. * `PROCESSING`: The session is currently processing modifications to its buckets. * `FINALIZING`: The session is currently generating result sets based on the contents of the buckets. The session will not accept new modifications to its buckets. * `COMPLETED`: The session has been completed and no further modifications can be made. * `FAILED`: The session failed to create result sets based on the contents of the buckets.' enum: - IDLE - PROCESSING - FINALIZING - COMPLETED - FAILED estimationMode: type: boolean description: 'If `true`, the session is in estimation mode. This implies that the summary may return estimates of the totals instead of exact counts and the contacts returned from the preview may be a subset of the total contacts that match the buckets. Note that the generated result sets from completing the session are always exact and are not based on estimates, regardless of whether the session is in estimation mode or not.' QueryResponse: type: object description: The CEM Results commands/result set IDs that were generated based on the modifications made to the session. properties: individual: $ref: '#/components/schemas/QueryResponseBucket' group: $ref: '#/components/schemas/QueryResponseBucket' rule: $ref: '#/components/schemas/QueryResponseBucket' query: $ref: '#/components/schemas/QueryResponseBucket' exclusion: $ref: '#/components/schemas/QueryResponseBucket' alert: $ref: '#/components/schemas/QueryResponseBucket' thread: $ref: '#/components/schemas/QueryResponseBucket' public: $ref: '#/components/schemas/QueryResponseBucket' Command: type: object required: - type properties: type: type: string description: The type of command to execute ApiPublicUserResultSet: type: object description: Include a set of public subscribers by a CEM Results ID (Result Set Identifier). properties: type: type: string enum: - ResultSet description: Must be set to `ResultSet`. resultSetId: type: string description: The unique system ID of the CEM Results to include. Only IDs in the `publicuser` or `resultset` domains are valid. example: evbg+result:publicuser:subscriptions:1697471720114 required: - type - resultSetId CemResultsBooleanPropertyQuery: allOf: - $ref: '#/components/schemas/CemResultsPropertyQuery' - type: object required: - type description: Provides querying against boolean properties in Contacts and Assets. properties: type: type: string description: Must be set to exactly `Boolean`. enum: - Boolean value: type: boolean description: A boolean value to match against the properties. PublicUserBucketData: type: object description: Include a set of public users via subscriptions. properties: public: type: array description: A list of subscriber queries to be included in the bucket. maxItems: 10 items: anyOf: - $ref: '#/components/schemas/ApiPublicUserResultSet' - $ref: '#/components/schemas/ApiPublicUserSemanticQuery' QueryResponseItemResultSetCommandFixedSet: type: object description: A `FixedSet` command for basic storage of resolved contacts or public users. properties: type: type: string enum: - FixedSet description: Must be set to `FixedSet`. items: type: array items: type: object description: An individual contact or public user. properties: id: type: string description: The unique system identifier of the contact or public user. featureId: type: - string - 'null' description: Not currently used. domain: type: string enum: - contact - publicuser description: The domain of the item, which indicates whether the item is a contact or a public user. properties: type: object description: A map of the item's properties, such as its original source. The properties available vary based on the domain of the item and the features included in the result set. rank: type: - string - 'null' description: Not currently used. required: - id - domain description: The list of CEM Results IDs of the result sets to filter. required: - type - items QueryBucketData: type: object description: Data to be stored in a bucket that supports generic queries. properties: query: type: array description: A list of generic queries to be included in the bucket. maxItems: 10 items: anyOf: - $ref: '#/components/schemas/ApiQueryResultSet' - $ref: '#/components/schemas/ApiQuerySemanticQuery' - $ref: '#/components/schemas/ApiQueryNotificationReportLog' ApiQueryNotificationReportLog: type: object description: Include a set of individual contacts and/or public users via the report log of an existing notification. properties: type: type: string enum: - NotificationReportLog description: Must be set to `NotificationReportLog`. notificationId: type: integer format: int64 description: The unique system ID of the notification. confirmationStatuses: type: array description: The list of confirmation statuses to include in the results. If empty, then contacts with any confirmation status will be included. items: type: string enum: - Confirmed - Attempted - ConfirmedLate - Unreachable - Duplicate - Dismissed pollResponses: type: array description: When used with a polling notification, filters the results by the responses that the recipients responded with to the poll. items: type: string segment: type: integer format: int32 minimum: 0 maximum: 9 default: 0 description: A logical separator to enable combining different subsets of a notification report log. For instance, retrieving all of those recipients who did not respond as well as those who responded with a certain poll response. required: - type - notificationId ApiQueryResultSet: type: object description: Include a set of individual contacts by a CEM Results ID (Result Set Identifier). properties: type: type: string enum: - ResultSet description: Must be set to `ResultSet`. resultSetId: type: string description: The unique system ID of the CEM Results to include. Only IDs in the `contact` or `resultset` domains are valid. example: evbg+result:contact:my-contacts:1697471720114 required: - type - resultSetId QueryResponseItemResultSetCommandFilter: type: object description: A `Filter` command for filtering another result set based on its items' properties. properties: type: type: string enum: - Filter description: Must be set to `Filter`. ids: type: array items: type: string description: The list of CEM Results IDs of the result sets to filter. properties: type: object description: A map of property names to the list of values to filter on. An item will be included in the results if it matches any of the values for any of the properties. features: type: boolean description: Whether to include the features of the items in the filtering. required: - type - ids CemResultsPropertyQuery: type: object required: - ids properties: ids: type: array description: The IDs of the properties to query by. ContactBucketData: type: object description: Data to be stored in a bucket that supports individual contacts. properties: contacts: type: array description: A list of individual contacts to be included in the bucket. maxItems: 5000 items: anyOf: - $ref: '#/components/schemas/ApiContactId' - $ref: '#/components/schemas/ApiContactExternalId' QueryResponseItemResultSetCommand: type: object description: The accumulated CEM Results command based on previous modifications to the bucket. properties: type: type: string enum: - ResultSetCommand description: Must be set to `ResultSetCommand`. id: type: string description: The unique system ID of the CEM Results command. The domain of the result set varies based on the `command`; valid domains may be any of `contact`, `publicuser`, `recipient`, or `resultset`. If the domain is `recipient` or `resultset`, then the tag will contain either `contact` or `publicuser` to help differentiate the type of results that will be returned from the command. example: evbg+result:recipient:comms-contact-builder-9e1077f6-91a2-4076-b301-fd9458a4ea3e:thread-notified-contact-0 command: type: object description: The CEM Result command body. oneOf: - $ref: '#/components/schemas/SemanticQuery' - $ref: '#/components/schemas/QueryResponseItemResultSetCommandRecipientsOf' - $ref: '#/components/schemas/QueryResponseItemResultSetCommandFilter' - $ref: '#/components/schemas/QueryResponseItemResultSetCommandFixedSet' required: - type - id - command CemResultsLastKnownLocationType: type: object description: Specifies how to include contacts with "Last Known" location types in CEM Results. required: - type properties: type: type: string description: Must be set to exactly `LastKnown`. enum: - LastKnown locationSourceIds: type: array description: A list of location source IDs. items: type: number CemResultsStringPropertyQuery: allOf: - $ref: '#/components/schemas/CemResultsPropertyQuery' - type: object required: - type description: Provides querying against string properties in Contacts and Assets. properties: type: type: string description: Must be set to exactly `String`. enum: - String values: type: array description: The values to match against the properties. items: type: string ProblemDetail: type: object description: An RFC-7807 compliant model for error details. properties: type: type: string description: A URI that identifies the problem type. title: type: string description: A short, human-readable summary of the problem type. status: type: integer description: The HTTP response status code describing the error. detail: type: string description: A human-readable explanation of the specific problem. instance: type: string description: A URI that identifies the specific problem. ApiRuleId: type: object description: Include a set of individual contacts by whether they match a contact rule (filter). properties: type: type: string enum: - Id description: Must be set to `Id`. ruleId: type: integer format: int64 description: The unique system ID of the contact rule (filter). required: - type - ruleId CreateSessionResponse: type: object description: Response body returned after starting a new Contact Builder session. properties: sessionId: type: string description: The unique identifier for the newly created session. example: 73ef9c42-df40-41c8-9b2d-6618ed5c31c1 expiration: type: string format: date-time description: The expiration time of the session in ISO 8601 format. example: '2024-07-03T20:06:09.734385Z' buckets: type: array description: A list of buckets created in the session. items: type: string description: The unique identifier for each bucket created in the session. required: - sessionId CemResultsNumberPropertyQuery: allOf: - $ref: '#/components/schemas/CemResultsPropertyQuery' - type: object required: - type description: Provides querying against numeric properties in Contacts and Assets. properties: type: type: string description: Must be set to exactly `Number`. enum: - Number lowerBound: type: number description: A lower bound to match against the properties. upperBound: type: number description: An upper bound to match against the properties. SummarySubsetTypes: type: object properties: groups: type: object description: A map of contact group IDs to the number of contacts in each group. additionalProperties: type: object properties: count: type: integer format: int64 description: The number of contacts in the session that are a part of this contact group. rules: type: object description: A map of contact rule (filter) IDs to the number of contacts that match the rule. additionalProperties: type: object properties: count: type: integer format: int64 description: The number of contacts in the session that match the rule. queries: type: object description: A map of CEM Result Set IDs to the number of contacts in each Result Set. additionalProperties: type: object properties: count: type: integer format: int64 description: The number of contacts that are included as a part of the Result Set. BaseApiPaginatedResponse: type: object properties: pages: type: object properties: currentPage: type: number description: The requested page number. pageSize: type: number description: The requested page size. pageCount: type: number description: The number of elements in the current page. totalPages: type: number description: The total number of pages available for request. maxSize: type: number description: The maximum size of a single page that is allowed by the API. totalCount: type: number description: The total number of elements across all pages. ApiContactExternalId: type: object description: Include an individual contact by their unique system ID. properties: type: type: string enum: - ExternalId description: Must be set to `ExternalId`. externalId: type: string description: The unique external ID of the contact. required: - type - externalId ResultResponse: type: object description: An object consisting of key-value pairs where the key is the name of the bucket and the value is zero or more CEM Results IDs generated for that bucket. properties: individual: type: array items: type: string group: type: array items: type: string rule: type: array items: type: string query: type: array items: type: string exclusion: type: array items: type: string alert: type: array items: type: string thread: type: array items: type: string description: Result sets from the `thread` bucket may be copied to the other buckets in the session if `threadSets` was provided. See the documentation for creating a session for more information. public: type: array items: type: string PublicBucketSummary: type: object properties: provisionalCount: type: integer format: int64 description: A provisional count of the number of public users that are in the current bucket. The actual number may be lower than this number when the session is ended. subscribedToIds: type: array description: The list of known subscription IDs that are included in the bucket. items: type: string CemResultsTravelLocationType: type: object description: Specifies how to include contacts with travel location types in CEM Results. required: - type properties: type: type: string description: Must be set to exactly `Travel`. enum: - Travel domesticInternationalStatuses: type: array description: A list of domestic international travel statuses. items: type: string localTravelStatuses: type: array description: A list of local travel statuses. items: type: string travelTypes: type: array description: Depicts whether a contact is arriving, departing, or transitioning to a location. items: type: string enum: - Arrival - Departure - Transit segmentTypes: type: array description: Depicts a contact's mode of transportation to a location. items: type: string enum: - Car - Hotel - Air - Rail BucketData: type: object description: Data to be stored in a bucket. properties: individual: $ref: '#/components/schemas/ContactBucketData' group: $ref: '#/components/schemas/GroupBucketData' rule: $ref: '#/components/schemas/RuleBucketData' query: $ref: '#/components/schemas/QueryBucketData' exclusion: $ref: '#/components/schemas/ContactBucketData' alert: anyOf: - $ref: '#/components/schemas/ContactBucketData' - $ref: '#/components/schemas/GroupBucketData' - $ref: '#/components/schemas/RuleBucketData' - $ref: '#/components/schemas/QueryBucketData' thread: anyOf: - $ref: '#/components/schemas/ContactBucketData' - $ref: '#/components/schemas/GroupBucketData' - $ref: '#/components/schemas/RuleBucketData' - $ref: '#/components/schemas/QueryBucketData' - $ref: '#/components/schemas/PublicUserBucketData' public: $ref: '#/components/schemas/PublicUserBucketData' CemResultsExpectedLocationType: type: object description: Specifies how to include contacts with expected location types in CEM Results. required: - type properties: type: type: string description: Must be set to exactly `Expected`. enum: - Expected GroupBucketData: type: object description: Data to be stored in a bucket that supports contact groups. properties: groups: type: array description: A list of contact groups to be included in the bucket. maxItems: 10 items: $ref: '#/components/schemas/ApiGroupId' ApiPublicUserSemanticQuery: type: object description: Include a set of public subscribers by a CEM Results `SemanticQuery`. properties: type: type: string enum: - SemanticQuery description: Must be set to `SemanticQuery`. command: $ref: '#/components/schemas/SemanticQuery' required: - type - command CemResultsCompleteName: type: object description: Used to describe a contact's complete name in a CEM Results query. required: - type - first - last properties: type: type: string description: Must be set to exactly `Complete`. enum: - Complete first: type: string description: The first name of the contact. last: type: string description: The last name of the contact. middleInitial: type: string description: The middle initial of the contact. suffix: type: string description: The suffix of the contact's name, such as "Jr." or "III". Geometry: type: object description: A geojson representation of a map shape. securitySchemes: API_Authorizer: type: apiKey name: Authorization in: header x-amazon-apigateway-authtype: custom x-amazon-apigateway-authorizer: authorizerUri: arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:214792946631:function:API_Authorizer_us-east-1_prod:live/invocations authorizerCredentials: arn:aws:iam::214792946631:role/comms-unified-gateway-prod-us-us-east-1-0-us-east-1-gw authorizerResultTtlInSeconds: 300 identitySource: method.request.header.Authorization,method.request.header.PathCacheKey,method.request.header.MethodCacheKey type: request api_key: type: apiKey name: x-api-key in: header x-readme: explorer-enabled: true proxy-enabled: true