diff --git a/services/external-actor-gateway-service/openapi.yaml b/services/external-actor-gateway-service/openapi.yaml index 1236182..d91a78b 100644 --- a/services/external-actor-gateway-service/openapi.yaml +++ b/services/external-actor-gateway-service/openapi.yaml @@ -19,6 +19,11 @@ security: components: callbacks: {} examples: + CreateAccountLogRequestExample: + description: Example values extracted from schema defaults + summary: CreateAccountLogRequest example + value: + type: webhook CreatePersonLogRequestExample: description: Example values extracted from schema defaults summary: CreatePersonLogRequest example @@ -32,6 +37,13 @@ components: headers: {} links: {} parameters: + AccountIdPath: + in: path + name: account_id + description: account_id parameter + required: true + schema: + type: string AudienceIdPath: in: path name: audience_id @@ -98,6 +110,12 @@ components: schema: $ref: "#/components/schemas/Error" description: Error response - covers authentication, authorization, rate limiting, and server errors + GetAccountResponseResponse: + description: Successful operation + content: + application/json: + schema: + $ref: "#/components/schemas/GetAccountResponse" GetWebhookSubscriptionResponseResponse: description: Successful operation content: @@ -111,10 +129,56 @@ components: $ref: "#/components/schemas/Error" description: Resource not found schemas: + UnnamedSchema: + type: string + minLength: 1 + pattern: ^prospectlog_[a-z0-9]{26}$ + AccountId: + type: string + minLength: 1 + pattern: ^account_[a-z0-9]{26}$ + description: Account ID ArraySchema: type: array items: $ref: "#/components/schemas/GetWebhookSubscriptionResponse" + CreateAccountLogRequest: + type: object + properties: + accountId: + $ref: "#/components/schemas/AccountId" + domain: + type: string + minLength: 1 + name: + type: string + minLength: 1 + maxLength: 255 + source: + type: string + minLength: 1 + maxLength: 100 + description: Identifier for the upstream system sending the account activity + type: + default: webhook + description: Account activity type. Defaults to 'webhook' when omitted + type: string + minLength: 1 + maxLength: 100 + idempotencyKey: + type: string + minLength: 1 + maxLength: 255 + payload: + type: object + propertyNames: + type: string + additionalProperties: {} + required: + - source + - type + - payload + additionalProperties: false CreateAudienceRequest: type: object properties: @@ -241,6 +305,195 @@ components: - message - requestId type: object + GetAccountResponse: + type: object + properties: + accountId: + $ref: "#/components/schemas/AccountId" + tenantId: + type: string + description: Tenant ID that owns the account + domain: + type: string + minLength: 1 + name: + anyOf: + - type: string + minLength: 1 + maxLength: 255 + - type: "null" + createdAt: + $ref: "#/components/schemas/CreatedAt" + updatedAt: + $ref: "#/components/schemas/CreatedAt" + latestActivityAt: + anyOf: + - $ref: "#/components/schemas/CreatedAt" + - type: "null" + linkedProspects: + type: array + items: + type: object + properties: + prospectId: + $ref: "#/components/schemas/PersonId" + tenantId: + type: string + description: Tenant ID that owns the prospect + name: + type: string + minLength: 1 + maxLength: 255 + description: Prospect display name + email: + anyOf: + - type: string + - type: "null" + domain: + anyOf: + - type: string + minLength: 1 + - type: "null" + slug: + type: string + minLength: 1 + maxLength: 255 + description: Prospect routing slug + phoneNumber: + anyOf: + - type: string + - type: "null" + linkedinProfileUrl: + anyOf: + - type: string + - type: "null" + createdAt: + $ref: "#/components/schemas/CreatedAt" + updatedAt: + $ref: "#/components/schemas/CreatedAt" + required: + - prospectId + - tenantId + - name + - email + - domain + - slug + - phoneNumber + - linkedinProfileUrl + - createdAt + - updatedAt + additionalProperties: false + required: + - accountId + - tenantId + - domain + - name + - createdAt + - updatedAt + - latestActivityAt + - linkedProspects + additionalProperties: false + GetActivity: + type: object + properties: + items: + type: array + items: + type: object + properties: + activityId: + type: string + minLength: 1 + description: Stable identifier for the activity item + activityType: + type: string + enum: + - account-log-entry + - prospect-log-entry + description: Whether the activity originated from the account itself or a linked prospect + accountId: + $ref: "#/components/schemas/AccountId" + accountLogId: + anyOf: + - $ref: "#/components/schemas/UnnamedSchema" + - type: "null" + prospectId: + anyOf: + - $ref: "#/components/schemas/PersonId" + - type: "null" + prospectLogId: + anyOf: + - $ref: "#/components/schemas/UnnamedSchema" + - type: "null" + prospectName: + anyOf: + - type: string + - type: "null" + source: + type: string + minLength: 1 + maxLength: 100 + description: Stored activity source + type: + type: string + minLength: 1 + maxLength: 100 + description: Stored activity type + payload: + type: object + propertyNames: + type: string + additionalProperties: {} + idempotencyKey: + anyOf: + - type: string + minLength: 1 + maxLength: 255 + - type: "null" + createdAt: + $ref: "#/components/schemas/CreatedAt" + updatedAt: + anyOf: + - $ref: "#/components/schemas/CreatedAt" + - type: "null" + deletedAt: + anyOf: + - $ref: "#/components/schemas/CreatedAt" + - type: "null" + required: + - activityId + - activityType + - accountId + - accountLogId + - prospectId + - prospectLogId + - prospectName + - source + - type + - payload + - idempotencyKey + - createdAt + - updatedAt + - deletedAt + additionalProperties: false + totalCount: + type: integer + minimum: 0 + maximum: 9007199254740991 + hasMore: + type: boolean + nextOffset: + anyOf: + - type: integer + minimum: 0 + maximum: 9007199254740991 + - type: "null" + required: + - items + - totalCount + - hasMore + - nextOffset + additionalProperties: false GetAudience: type: object properties: @@ -405,8 +658,6 @@ components: createdAt: $ref: "#/components/schemas/CreatedAt" deletedAt: - "0": - $ref: "#/components/schemas/CreatedAt" anyOf: - $ref: "#/components/schemas/CreatedAt" - type: "null" @@ -468,8 +719,6 @@ components: type: array items: {} deletedAt: - "0": - $ref: "#/components/schemas/CreatedAt" anyOf: - $ref: "#/components/schemas/CreatedAt" - type: "null" @@ -570,6 +819,33 @@ components: type: string minLength: 1 pattern: ^prospect_[a-z0-9]{26}$ + description: Linked prospect ID + PostAccountLog: + type: object + properties: + accountId: + $ref: "#/components/schemas/AccountId" + accountLogId: + $ref: "#/components/schemas/UnnamedSchema" + createdAt: + $ref: "#/components/schemas/CreatedAt" + source: + type: string + minLength: 1 + maxLength: 100 + description: The stored account log source + type: + type: string + minLength: 1 + maxLength: 100 + description: The stored account log type + required: + - accountId + - accountLogId + - createdAt + - source + - type + additionalProperties: false PostAudience: type: object properties: @@ -602,10 +878,7 @@ components: personId: $ref: "#/components/schemas/PersonId" personLogId: - type: string - minLength: 1 - pattern: ^prospectlog_[a-z0-9]{26}$ - description: The created person log entry ID + $ref: "#/components/schemas/UnnamedSchema" createdAt: $ref: "#/components/schemas/CreatedAt" createdPerson: @@ -669,6 +942,17 @@ components: - updatedAt - signingSecret additionalProperties: false + UpdateAccountRequest: + type: object + properties: + name: + type: string + minLength: 1 + maxLength: 255 + description: New account name + required: + - name + additionalProperties: false UpdateWebhookSubscriptionRequest: type: object properties: @@ -699,6 +983,90 @@ components: name: x-api-key type: apiKey paths: + /v0/account_logs: + post: + description: Create an account log entry using the authenticated API key's tenant context + operationId: createAccountLog + responses: + "201": + description: AccountLog created successfully + content: + application/json: + schema: + $ref: "#/components/schemas/PostAccountLog" + summary: Create account log entry + tags: + - Account Logs + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/CreateAccountLogRequest" + required: true + /v0/accounts/{account_id}: + get: + description: Retrieve a specific account by ID. + operationId: getAccount + responses: + "200": + $ref: "#/components/responses/GetAccountResponseResponse" + summary: Get account by ID + tags: + - Accounts + parameters: + - $ref: "#/components/parameters/AccountIdPath" + patch: + description: Update an account by ID + operationId: updateAccount + responses: + "200": + $ref: "#/components/responses/GetAccountResponseResponse" + summary: Update account by ID + tags: + - Accounts + parameters: + - $ref: "#/components/parameters/AccountIdPath" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/UpdateAccountRequest" + required: true + /v0/accounts/{account_id}/activity: + get: + description: Retrieve merged account activity, optionally including linked prospect activity + operationId: listAccountActivity + responses: + "200": + description: Successful operation + content: + application/json: + schema: + $ref: "#/components/schemas/GetActivity" + summary: List account activity + tags: + - Account Activity + parameters: + - in: query + name: includeProspectActivity + description: includeProspectActivity parameter + required: false + schema: + type: string + - in: query + name: includeDeleted + description: includeDeleted parameter + required: false + schema: + type: string + - $ref: "#/components/parameters/LimitQuery" + - in: query + name: offset + description: offset parameter + required: false + schema: + type: number + - $ref: "#/components/parameters/AccountIdPath" /v0/pages: get: description: Retrieve a list of pages for the authenticated tenant with optional filtering and pagination @@ -978,7 +1346,13 @@ tags: description: Audience management operations - name: Audience Versions description: Audience version management operations + - name: Accounts + description: Account read and update operations + - name: Account Activity + description: Merged account and linked prospect activity operations - name: Person Logs description: Person log ingestion operations + - name: Account Logs + description: Account log ingestion operations - name: Webhook Subscriptions description: Webhook subscription management operations