openapi: 3.0.0 info: title: Hightouch Events API description: Hightouch Public Rest API to access syncs, models, sources and destinations version: 1.0.0 contact: name: Hightouch url: https://hightouch.com x-harvested-from: https://api.hightouch.io/api/swagger.json x-harvested-on: '2026-08-13' x-source-document: openapi/_original/hightouch-api-openapi.json servers: - url: https://api.hightouch.com/api/v1 tags: - name: Events paths: /events/contracts/{contractId}: get: operationId: GetContract responses: '200': description: Ok content: application/json: schema: anyOf: - $ref: '#/components/schemas/EventContract' - $ref: '#/components/schemas/ValidateErrorJSON' - $ref: '#/components/schemas/InternalServerError' examples: Example 1: value: id: '1' name: My Contract slug: my-contract workspaceId: 1 events: - type: track name: Checked Out slug: track-checked-out version: default schema: type: object required: - req properties: req: type: string description: '' onSchemaViolation: ALLOW_EVENT onUndeclaredFields: BLOCK_EVENT onUndeclaredSchema: BLOCK_EVENT eventSources: - id: '1' name: Marketing Site createdAt: '2022-02-16T21:37:58.510Z' updatedAt: '2022-02-16T21:37:58.510Z' '401': description: Unauthorized '404': description: Not found '422': description: Validation Failed content: application/json: schema: $ref: '#/components/schemas/ValidateErrorJSON' description: Retrieve a contract based on its contract ID summary: Get Contract security: - bearerAuth: [] parameters: - description: The id of the contract in: path name: contractId required: true schema: type: string tags: - Events patch: operationId: UpdateContract responses: '200': description: Ok content: application/json: schema: anyOf: - $ref: '#/components/schemas/EventContractUpdate' - $ref: '#/components/schemas/ValidateErrorJSON' - $ref: '#/components/schemas/InternalServerError' examples: Example 1: value: id: '1' name: My Contract workspaceId: 1 events: - type: track name: Checked Out slug: track-checked-out version: default schema: type: object required: - req properties: req: type: string description: '' onSchemaViolation: ALLOW_EVENT onUndeclaredFields: BLOCK_EVENT onUndeclaredSchema: BLOCK_EVENT eventSources: - id: '1' name: Marketing Site createdAt: '2022-02-16T21:37:58.510Z' updatedAt: '2022-02-16T21:37:58.510Z' '401': description: Unauthorized '403': description: Forbidden '404': description: Not found '422': description: Validation Failed content: application/json: schema: $ref: '#/components/schemas/ValidateErrorJSON' '500': description: Something went wrong content: application/json: schema: $ref: '#/components/schemas/InternalServerError' description: 'Update an existing event contract Patch an event contract based on its Hightouch ID' summary: Update an Event Contract security: - bearerAuth: [] parameters: - in: path name: contractId required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/EventContractUpdate' example: events: - type: track name: Checked Out onUndeclaredFields: BLOCK_EVENT onSchemaViolation: BLOCK_EVENT schema: type: object properties: properties: type: object required: - total properties: total: type: number tags: - Events /events/contracts: get: operationId: ListContracts responses: '200': description: Ok content: application/json: schema: properties: data: items: $ref: '#/components/schemas/EventContract' type: array required: - data type: object examples: Example 1: value: data: - id: '1' name: My Contract slug: my-contract workspaceId: 1 events: - type: track name: Checked Out slug: track-checked-out version: default schema: type: object required: - req properties: req: type: string description: '' onSchemaViolation: BLOCK_EVENT onUndeclaredFields: BLOCK_EVENT onUndeclaredSchema: BLOCK_EVENT eventSources: - id: '1' name: Marketing Site createdAt: '2022-02-16T21:37:58.510Z' updatedAt: '2022-02-16T21:37:58.510Z' hasMore: false '400': description: Bad request '401': description: Unauthorized '422': description: Validation Failed content: application/json: schema: $ref: '#/components/schemas/ValidateErrorJSON' description: List all event contracts in the current workspace summary: List Event Contracts security: - bearerAuth: [] parameters: - in: query name: name required: false schema: type: string - description: set the offset on results (for pagination) in: query name: offset required: false schema: default: 0 format: double type: number - description: limit the number of objects returned (default is 100) in: query name: limit required: false schema: default: 100 format: double type: number - description: specify the order in: query name: orderBy required: false schema: default: id type: string enum: - id - name - createdAt - updatedAt tags: - Events post: operationId: CreateContract responses: '200': description: Ok content: application/json: schema: anyOf: - $ref: '#/components/schemas/EventContract' - $ref: '#/components/schemas/ValidateErrorJSON' - $ref: '#/components/schemas/InternalServerError' examples: Example 1: value: id: '1' name: My Contract workspaceId: 1 events: - type: track name: Checked Out version: default schema: type: object required: - req properties: req: type: string description: '' onSchemaViolation: ALLOW_EVENT onUndeclaredFields: BLOCK_EVENT onUndeclaredSchema: BLOCK_EVENT eventSources: - id: '1' name: Marketing Site createdAt: '2022-02-16T21:37:58.510Z' updatedAt: '2022-02-16T21:37:58.510Z' '401': description: Unauthorized '403': description: Forbidden '422': description: Validation Failed content: application/json: schema: $ref: '#/components/schemas/ValidateErrorJSON' '500': description: Something went wrong content: application/json: schema: $ref: '#/components/schemas/InternalServerError' description: Create a new event contract summary: Create an Event Contract security: - bearerAuth: [] parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/EventContractCreate' example: name: My Contract events: - type: track name: Checked Out onUndeclaredFields: ALLOW_EVENT onSchemaViolation: BLOCK_EVENT schema: type: object properties: properties: type: object required: - total properties: total: type: number tags: - Events /events/domains/{domainId}: get: operationId: GetDomain responses: '200': description: Ok content: application/json: schema: anyOf: - $ref: '#/components/schemas/EventDomain' - $ref: '#/components/schemas/ValidateErrorJSON' - $ref: '#/components/schemas/InternalServerError' '401': description: Unauthorized '404': description: Not found '422': description: Validation Failed content: application/json: schema: $ref: '#/components/schemas/ValidateErrorJSON' description: Retrieve a domain by its id, including its events and components. summary: Get Domain security: - bearerAuth: [] parameters: - description: The id of the domain in: path name: domainId required: true schema: type: string tags: - Events patch: operationId: UpdateDomain responses: '200': description: Ok content: application/json: schema: anyOf: - $ref: '#/components/schemas/EventDomain' - $ref: '#/components/schemas/ValidateErrorJSON' - $ref: '#/components/schemas/InternalServerError' '401': description: Unauthorized '403': description: Forbidden '404': description: Not found '422': description: Validation Failed content: application/json: schema: $ref: '#/components/schemas/ValidateErrorJSON' '500': description: Something went wrong content: application/json: schema: $ref: '#/components/schemas/InternalServerError' description: Update an existing event domain, replacing its events and components. summary: Update an Event Domain security: - bearerAuth: [] parameters: - description: The domain's id in: path name: domainId required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/EventDomainUpdate' tags: - Events /events/domains: get: operationId: ListDomains responses: '200': description: Ok content: application/json: schema: properties: data: items: $ref: '#/components/schemas/EventDomain' type: array required: - data type: object '400': description: Bad request '401': description: Unauthorized '422': description: Validation Failed content: application/json: schema: $ref: '#/components/schemas/ValidateErrorJSON' description: List all event domains in the current workspace. summary: List Event Domains security: - bearerAuth: [] parameters: - in: query name: name required: false schema: type: string - description: set the offset on results (for pagination) in: query name: offset required: false schema: default: 0 format: double type: number - description: limit the number of objects returned (default is 100) in: query name: limit required: false schema: default: 100 format: double type: number - description: specify the order in: query name: orderBy required: false schema: default: id type: string enum: - id - name - createdAt - updatedAt tags: - Events post: operationId: CreateDomain responses: '200': description: Ok content: application/json: schema: anyOf: - $ref: '#/components/schemas/EventDomain' - $ref: '#/components/schemas/ValidateErrorJSON' - $ref: '#/components/schemas/InternalServerError' '401': description: Unauthorized '403': description: Forbidden '422': description: Validation Failed content: application/json: schema: $ref: '#/components/schemas/ValidateErrorJSON' '500': description: Something went wrong content: application/json: schema: $ref: '#/components/schemas/InternalServerError' description: Create a new event domain, with its events and components. summary: Create an Event Domain security: - bearerAuth: [] parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/EventDomainCreate' tags: - Events components: schemas: EventContract: description: A collection of schemas that are used for validating your events. properties: id: type: string description: The contract's id name: type: string description: The contract's name slug: type: string description: The contract's slug. If not specified, one will be generated. description: type: string description: The contract's description onUndeclaredSchema: type: string enum: - ALLOW_EVENT - BLOCK_EVENT description: 'What happens to events that aren''t defined in the contract. One of ALLOW_EVENT or BLOCK_EVENT. Optional, defaults to ALLOW_EVENT.' events: items: properties: schema: properties: {} additionalProperties: {} type: object description: The JSON schema that validates the event. Required. onUndeclaredFields: type: string enum: - ALLOW_EVENT - BLOCK_EVENT - OMIT_FIELDS description: 'What happens to events that contain fields not in the schema. One of ALLOW_EVENT, BLOCK_EVENT, or OMIT_FIELDS. Optional, defaults to OMIT_FIELDS.' onSchemaViolation: type: string enum: - ALLOW_EVENT - BLOCK_EVENT description: 'What happens to events that violate the schema. One of ALLOW_EVENT or BLOCK_EVENT. Optional, defaults to BLOCK_EVENT.' version: type: string description: The event version. Defaults to "default", optional. You probably don't need to set this. slug: type: string description: The event's slug. If not specified, one will be generated. name: type: string description: The event's name. Required for track events. type: type: string enum: - track - identify - page - screen - group description: The event's type. One of track, identify, page, screen, or group. Required. required: - schema - type type: object type: array description: The definitions for the events in the contract. workspaceId: type: number format: double description: The id of the workspace that the contract belongs to createdAt: type: string format: date-time description: The timestamp when the contract was created updatedAt: type: string format: date-time description: The timestamp when the contract was last updated eventSources: items: properties: name: type: string id: type: string required: - name - id type: object type: array description: The Event Sources linked to the Contract. required: - id - name - workspaceId - createdAt - updatedAt - eventSources type: object additionalProperties: false EventContractCreate: description: The input for creating a Contract properties: name: type: string description: The contract's name slug: type: string description: The contract's slug. If not specified, one will be generated. description: type: string description: The contract's description onUndeclaredSchema: type: string enum: - ALLOW_EVENT - BLOCK_EVENT description: 'What happens to events that aren''t defined in the contract. One of ALLOW_EVENT or BLOCK_EVENT. Optional, defaults to ALLOW_EVENT.' events: items: properties: schema: properties: {} additionalProperties: {} type: object description: The JSON schema that validates the event. Required. onUndeclaredFields: type: string enum: - ALLOW_EVENT - BLOCK_EVENT - OMIT_FIELDS description: 'What happens to events that contain fields not in the schema. One of ALLOW_EVENT, BLOCK_EVENT, or OMIT_FIELDS. Optional, defaults to OMIT_FIELDS.' onSchemaViolation: type: string enum: - ALLOW_EVENT - BLOCK_EVENT description: 'What happens to events that violate the schema. One of ALLOW_EVENT or BLOCK_EVENT. Optional, defaults to BLOCK_EVENT.' version: type: string description: The event version. Defaults to "default", optional. You probably don't need to set this. slug: type: string description: The event's slug. If not specified, one will be generated. name: type: string description: The event's name. Required for track events. type: type: string enum: - track - identify - page - screen - group description: The event's type. One of track, identify, page, screen, or group. Required. required: - schema - type type: object type: array description: The definitions for the events in the contract. required: - name type: object additionalProperties: false EventContractUpdate: description: The input for updating a Contract properties: name: type: string description: The contract's name slug: type: string description: The contract's slug. If not specified, one will be generated. description: type: string description: The contract's description onUndeclaredSchema: type: string enum: - ALLOW_EVENT - BLOCK_EVENT description: 'What happens to events that aren''t defined in the contract. One of ALLOW_EVENT or BLOCK_EVENT. Optional, defaults to ALLOW_EVENT.' events: items: properties: schema: properties: {} additionalProperties: {} type: object description: The JSON schema that validates the event. Required. onUndeclaredFields: type: string enum: - ALLOW_EVENT - BLOCK_EVENT - OMIT_FIELDS description: 'What happens to events that contain fields not in the schema. One of ALLOW_EVENT, BLOCK_EVENT, or OMIT_FIELDS. Optional, defaults to OMIT_FIELDS.' onSchemaViolation: type: string enum: - ALLOW_EVENT - BLOCK_EVENT description: 'What happens to events that violate the schema. One of ALLOW_EVENT or BLOCK_EVENT. Optional, defaults to BLOCK_EVENT.' version: type: string description: The event version. Defaults to "default", optional. You probably don't need to set this. slug: type: string description: The event's slug. If not specified, one will be generated. name: type: string description: The event's name. Required for track events. type: type: string enum: - track - identify - page - screen - group description: The event's type. One of track, identify, page, screen, or group. Required. required: - schema - type type: object type: array description: The definitions for the events in the contract. type: object additionalProperties: false EventDomain: description: A collection of event and component schemas used for validating events. properties: id: type: string description: The domain's id name: type: string description: The domain's name slug: type: string description: The domain's slug. If not specified, one will be generated. description: type: string description: The domain's description onUndeclaredSchema: type: string enum: - ALLOW_EVENT - BLOCK_EVENT description: 'What happens to events that aren''t defined in the domain. One of ALLOW_EVENT or BLOCK_EVENT. Optional, defaults to ALLOW_EVENT.' events: items: properties: schema: properties: {} additionalProperties: {} type: object description: The JSON schema that validates the event. Required. May contain component `$ref`s. onUndeclaredFields: type: string enum: - ALLOW_EVENT - BLOCK_EVENT - OMIT_FIELDS description: 'What happens to events that contain fields not in the schema. One of ALLOW_EVENT, BLOCK_EVENT, or OMIT_FIELDS. Optional, defaults to OMIT_FIELDS.' onSchemaViolation: type: string enum: - ALLOW_EVENT - BLOCK_EVENT description: 'What happens to events that violate the schema. One of ALLOW_EVENT or BLOCK_EVENT. Optional, defaults to BLOCK_EVENT.' version: type: string description: The event version. Defaults to "default", optional. You probably don't need to set this. slug: type: string description: The event's slug. If not specified, one will be generated. name: type: string description: The event's name. Required for track events. type: type: string enum: - track - identify - page - screen - group description: The event's type. One of track, identify, page, screen, or group. Required. required: - schema - type type: object type: array description: The definitions for the events in the domain. components: items: $ref: '#/components/schemas/EventDomainComponent' type: array description: The reusable components defined in the domain. workspaceId: type: number format: double description: The id of the workspace that the domain belongs to createdAt: type: string format: date-time description: The timestamp when the domain was created updatedAt: type: string format: date-time description: The timestamp when the domain was last updated eventSources: items: properties: name: type: string id: type: string required: - name - id type: object type: array description: The Event Sources linked to the Domain. required: - id - name - workspaceId - createdAt - updatedAt - eventSources type: object additionalProperties: false EventDomainComponent: description: Reusable schema fragments that can be imported by event schemas. properties: id: type: string description: The component's id. Omit when creating. On update, a component matches an existing one by id when supplied, otherwise by (name, version); include the id to rename a component in place. slug: type: string description: The component's slug. Optional when creating; generated from the name if omitted. Immutable after creation; an update that sends a different slug for an existing component is rejected. name: type: string description: The component's name. Required. version: type: string description: The component's version. Defaults to "default", optional. On update, an omitted version keeps the stored value when the component is matched by id; without an id, an omitted version only matches the stored "default" version, and the request is rejected if the name exists only under other versions. description: type: string description: The component's description. On update, an omitted description keeps the stored value; send an empty string to clear it. schema: properties: {} additionalProperties: {} type: object description: The JSON schema fragment the component contributes. Required. imports: items: type: string type: array description: 'Read-only: the slugs of the components this component imports (derived from its `$ref`s).' required: - name - schema type: object additionalProperties: false EventDomainCreate: description: The input for creating a Domain properties: name: type: string description: The domain's name slug: type: string description: The domain's slug. If not specified, one will be generated. description: type: string description: The domain's description onUndeclaredSchema: type: string enum: - ALLOW_EVENT - BLOCK_EVENT description: 'What happens to events that aren''t defined in the domain. One of ALLOW_EVENT or BLOCK_EVENT. Optional, defaults to ALLOW_EVENT.' events: items: properties: schema: properties: {} additionalProperties: {} type: object description: The JSON schema that validates the event. Required. May contain component `$ref`s. onUndeclaredFields: type: string enum: - ALLOW_EVENT - BLOCK_EVENT - OMIT_FIELDS description: 'What happens to events that contain fields not in the schema. One of ALLOW_EVENT, BLOCK_EVENT, or OMIT_FIELDS. Optional, defaults to OMIT_FIELDS.' onSchemaViolation: type: string enum: - ALLOW_EVENT - BLOCK_EVENT description: 'What happens to events that violate the schema. One of ALLOW_EVENT or BLOCK_EVENT. Optional, defaults to BLOCK_EVENT.' version: type: string description: The event version. Defaults to "default", optional. You probably don't need to set this. slug: type: string description: The event's slug. If not specified, one will be generated. name: type: string description: The event's name. Required for track events. type: type: string enum: - track - identify - page - screen - group description: The event's type. One of track, identify, page, screen, or group. Required. required: - schema - type type: object type: array description: The definitions for the events in the domain. components: items: $ref: '#/components/schemas/EventDomainComponent' type: array description: The reusable components defined in the domain. required: - name type: object additionalProperties: false EventDomainUpdate: description: The input for updating a Domain properties: name: type: string description: The domain's name slug: type: string description: The domain's slug. If not specified, one will be generated. description: type: string description: The domain's description onUndeclaredSchema: type: string enum: - ALLOW_EVENT - BLOCK_EVENT description: 'What happens to events that aren''t defined in the domain. One of ALLOW_EVENT or BLOCK_EVENT. Optional, defaults to ALLOW_EVENT.' events: items: properties: schema: properties: {} additionalProperties: {} type: object description: The JSON schema that validates the event. Required. May contain component `$ref`s. onUndeclaredFields: type: string enum: - ALLOW_EVENT - BLOCK_EVENT - OMIT_FIELDS description: 'What happens to events that contain fields not in the schema. One of ALLOW_EVENT, BLOCK_EVENT, or OMIT_FIELDS. Optional, defaults to OMIT_FIELDS.' onSchemaViolation: type: string enum: - ALLOW_EVENT - BLOCK_EVENT description: 'What happens to events that violate the schema. One of ALLOW_EVENT or BLOCK_EVENT. Optional, defaults to BLOCK_EVENT.' version: type: string description: The event version. Defaults to "default", optional. You probably don't need to set this. slug: type: string description: The event's slug. If not specified, one will be generated. name: type: string description: The event's name. Required for track events. type: type: string enum: - track - identify - page - screen - group description: The event's type. One of track, identify, page, screen, or group. Required. required: - schema - type type: object type: array description: The definitions for the events in the domain. components: items: $ref: '#/components/schemas/EventDomainComponent' type: array description: The reusable components defined in the domain. type: object additionalProperties: false InternalServerError: type: string enum: - Internal Server Error nullable: false ValidateErrorJSON: properties: message: type: string enum: - Validation failed nullable: false details: properties: {} additionalProperties: {} type: object required: - message - details type: object additionalProperties: false securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: Bearer security: - bearerAuth: []