--- title: "Create a call entry" url: "https://developers.zinnia.com/apis/orion-api/versions/716288b7-e96e-41a7-abc5-63925410717a/operations/create-call-entry" --- > Full API specification: https://developers.zinnia.com/apis/orion-api/versions/716288b7-e96e-41a7-abc5-63925410717a.md # Create a call entry `POST` `/callcenter/v1/CallEntry` Operation ID: `create-call-entry` Creates a call record for the company identified by `X-Client-Code` and returns the complete created `CallEntry`. The request must include `callerName` and a valid active `callerType`. `callType`, `transactionType`, and `productType` are matched without regard to letter casing and resolved to the company's active canonical lookup values. A call without contracts must provide a top-level `callType`. When contracts are provided, the top-level `callType` becomes the default for any contract that does not provide its own `callTypes`. Contract-specific values override that default. If no top-level `callType` is supplied, every contract must provide at least one call type. Orion determines the acting user from the configured token identity claims. If none of these claims is present, Orion uses the trimmed `userName` from the request body to identify the caller in machine-to-machine scenarios. `X-Correlation-Id` makes the request idempotent for at least 24 hours. The first successful request returns `201 Created`. A completed identical replay returns the original record with `200 OK` and `X-Idempotent-Replay: true`, without processing the creation again. Reusing the ID for different content or while the original request is still running returns `409 Conflict`. ## Header parameters - `X-Client-Code` (string, required) - Required tenant selector. Trimmed and resolved case-insensitively to a canonical configured tenant before FGA authorization; missing, blank, or unknown values return 400. - `X-Correlation-Id` (string, required) - Required trimmed, nonblank idempotency key, maximum 100 characters. Scoped by canonical tenant, operation, and resource identity; clients must generate operation-unique values. ## Request body (required) Content types: `application/json`, `text/json`, `application/*+json` ## Responses - `200` - OK. Identical completed create replay; returns the original full CallEntry without processing the creation again. - `201` - Created. Returns the full CallEntry representation. - `400` - Bad Request. Missing/blank/unknown tenant, invalid correlation ID, missing conditional M2M userName, invalid fields, unknown/inactive lookup names, or contract classification/duplication errors. - `401` - Unauthorized. Bearer token is missing, malformed, or fails configured authentication validation. - `403` - Forbidden. Token lacks partyId, tenant FGA read/write authorization, or contains a present but blank/malformed configured username claim on a write. - `409` - Conflict. The scoped X-Correlation-Id was reused with different normalized content or actor, or an equivalent request is still in progress. - `503` - Service Unavailable (503). FGA returned an unavailable/unusable result, or the selected tenant has duplicate active lookup names and Orion will not choose an arbitrary ID. ## OpenAPI definition ```yaml openapi: 3.0.4 info: title: Orion Call Center API version: v1 servers: - url: https://qa.api.zinnia.io paths: /callcenter/v1/CallEntry: post: tags: - Call Entries summary: Create a call entry description: >- Creates a call record for the company identified by `X-Client-Code` and returns the complete created `CallEntry`. The request must include `callerName` and a valid active `callerType`. `callType`, `transactionType`, and `productType` are matched without regard to letter casing and resolved to the company's active canonical lookup values. A call without contracts must provide a top-level `callType`. When contracts are provided, the top-level `callType` becomes the default for any contract that does not provide its own `callTypes`. Contract-specific values override that default. If no top-level `callType` is supplied, every contract must provide at least one call type. Orion determines the acting user from the configured token identity claims. If none of these claims is present, Orion uses the trimmed `userName` from the request body to identify the caller in machine-to-machine scenarios. `X-Correlation-Id` makes the request idempotent for at least 24 hours. The first successful request returns `201 Created`. A completed identical replay returns the original record with `200 OK` and `X-Idempotent-Replay: true`, without processing the creation again. Reusing the ID for different content or while the original request is still running returns `409 Conflict`. operationId: create-call-entry parameters: - name: X-Client-Code in: header description: Required tenant selector. Trimmed and resolved case-insensitively to a canonical configured tenant before FGA authorization; missing, blank, or unknown values return 400. required: true schema: maxLength: 4 minLength: 3 pattern: ^[A-Za-z]{3,4}$ type: string example: ABCD - name: X-Correlation-Id in: header description: Required trimmed, nonblank idempotency key, maximum 100 characters. Scoped by canonical tenant, operation, and resource identity; clients must generate operation-unique values. required: true schema: maxLength: 100 minLength: 1 pattern: ^[A-Za-z0-9._:-]+$ type: string example: call-entry-create-123 requestBody: description: Full-field name-based create payload. Unknown JSON properties retain permissive framework handling. userName is conditionally required only for interim M2M tokens with no configured username claim. content: application/json: schema: $ref: "#/components/schemas/CallEntryWriteRequest" example: callerName: Jane Caller callerType: Owner callType: Billing transactionType: Payment productType: Annuity contracts: - contractNumber: C-10001 callTypes: - Billing text/json: schema: $ref: "#/components/schemas/CallEntryWriteRequest" application/*+json: schema: $ref: "#/components/schemas/CallEntryWriteRequest" required: true responses: "200": description: OK. Identical completed create replay; returns the original full CallEntry without processing the creation again. headers: X-Idempotent-Replay: description: Present with value true only for a completed idempotent replay. schema: type: boolean example: true content: text/plain: schema: $ref: "#/components/schemas/CallEntry" application/json: schema: $ref: "#/components/schemas/CallEntry" text/json: schema: $ref: "#/components/schemas/CallEntry" "201": description: Created. Returns the full CallEntry representation. headers: Location: description: Directly dereferenceable relative legacy GET URI containing the canonical tenant query value. schema: type: string format: uri-reference example: /callcenter/v1/CallEntry/12345?clientCode=ABCD content: text/plain: schema: $ref: "#/components/schemas/CallEntry" application/json: schema: $ref: "#/components/schemas/CallEntry" text/json: schema: $ref: "#/components/schemas/CallEntry" "400": description: Bad Request. Missing/blank/unknown tenant, invalid correlation ID, missing conditional M2M userName, invalid fields, unknown/inactive lookup names, or contract classification/duplication errors. content: text/plain: schema: $ref: "#/components/schemas/Response" application/json: schema: $ref: "#/components/schemas/Response" text/json: schema: $ref: "#/components/schemas/Response" "401": description: Unauthorized. Bearer token is missing, malformed, or fails configured authentication validation. content: text/plain: schema: $ref: "#/components/schemas/Response" application/json: schema: $ref: "#/components/schemas/Response" text/json: schema: $ref: "#/components/schemas/Response" "403": description: Forbidden. Token lacks partyId, tenant FGA read/write authorization, or contains a present but blank/malformed configured username claim on a write. content: text/plain: schema: $ref: "#/components/schemas/Response" application/json: schema: $ref: "#/components/schemas/Response" text/json: schema: $ref: "#/components/schemas/Response" "409": description: Conflict. The scoped X-Correlation-Id was reused with different normalized content or actor, or an equivalent request is still in progress. content: text/plain: schema: $ref: "#/components/schemas/Response" application/json: schema: $ref: "#/components/schemas/Response" text/json: schema: $ref: "#/components/schemas/Response" "503": description: Service Unavailable (503). FGA returned an unavailable/unusable result, or the selected tenant has duplicate active lookup names and Orion will not choose an arbitrary ID. content: text/plain: schema: $ref: "#/components/schemas/Response" application/json: schema: $ref: "#/components/schemas/Response" text/json: schema: $ref: "#/components/schemas/Response" security: - Bearer: [] security: - Bearer: [] components: schemas: CallEntryWriteRequest: required: - callerName - callerType type: object properties: userName: maxLength: 254 minLength: 1 pattern: ^[^\u0000-\u001F\u007F]+$ type: string description: Conditional interim M2M actor. Ignored when a configured token username claim exists; otherwise trimmed, opaque, required, and limited to 255 characters. nullable: true contracts: type: array items: $ref: "#/components/schemas/CallEntryWriteContractRequest" description: Optional contracts; missing, null, and empty are equivalent. Contract and call-type order is non-semantic for idempotency. nullable: true callerType: maxLength: 50 minLength: 1 pattern: ^[A-Za-z0-9 &'/-]+$ type: string description: Required active caller-type name, trimmed and matched case-insensitively to its canonical tenant value. nullable: true callType: maxLength: 50 minLength: 1 pattern: ^[A-Za-z0-9 &'/-]+$ type: string description: Canonical root call-type name. Required without contracts; otherwise supplies an inheritable default. If absent, every contract must supply at least one call type. nullable: true productType: maxLength: 50 minLength: 1 pattern: ^[A-Za-z0-9 &'/-]+$ type: string description: Optional active product-type name resolved to its canonical tenant value. nullable: true priority: maximum: 255 minimum: 0 type: integer format: int32 nullable: true notes: maxLength: 7000 minLength: 1 pattern: ^[A-Za-z0-9 &'/-]+$ type: string nullable: true survey: maxLength: 10 minLength: 1 pattern: ^[A-Za-z0-9 &'/-]+$ enum: - Not Offered - Taken - Not Taken type: string nullable: true isExchange: type: boolean nullable: true isSuspended: type: boolean nullable: true isFollowUpCompleted: type: boolean nullable: true followUpRequestedDate: type: string format: date-time nullable: true followUpCompletedDate: type: string format: date-time nullable: true suspendedUntilDate: type: string format: date-time nullable: true callTime: type: string format: date-time nullable: true callerName: maxLength: 500 minLength: 1 pattern: ^[A-Za-z ,.'-]+$ type: string description: Required caller identity. Trimmed and limited to 500 characters. nullable: true phoneFaxNum: maxLength: 20 minLength: 1 pattern: ^\+?[0-9() .-]+$ type: string format: tel nullable: true reference: maxLength: 200 minLength: 1 pattern: ^[A-Za-z0-9,-]+$ type: string nullable: true isWatchOne: type: boolean nullable: true isWatchTwo: type: boolean nullable: true transactionType: maxLength: 50 minLength: 1 pattern: ^[A-Za-z0-9 &'/-]+$ type: string description: Optional active transaction-type name resolved to its canonical tenant value. nullable: true isEscalated: type: boolean nullable: true initiatedDate: type: string format: date-time nullable: true completeInOrion: type: boolean nullable: true isWatchThree: type: boolean nullable: true transactionAmount: type: number format: double nullable: true sessionID: maxLength: 50 minLength: 1 pattern: ^[A-Za-z0-9._:-]+$ type: string nullable: true authStatus: type: string nullable: true dob: type: string format: date-time nullable: true ssn: type: string nullable: true callSummary: maxLength: 7000 minLength: 1 pattern: ^[A-Za-z0-9 &'/-]+$ type: string nullable: true callSummaryDate: type: string format: date-time nullable: true documentNumber: maxLength: 50 minLength: 1 pattern: ^[A-Za-z0-9,-]+$ type: string nullable: true callId: maxLength: 50 minLength: 1 pattern: ^[A-Za-z0-9._:/-]+$ type: string nullable: true additionalProperties: false description: Full-field name-based request shared by POST and PUT. Tenant selection and authorization never use payload userName. CallEntry: required: - callEntryID - clientCode - createdByUser - createdDate - lastUpdatedDate type: object properties: clientCode: minLength: 1 type: string callEntryID: type: integer format: int32 callerTypeID: type: integer format: int32 nullable: true callerType: type: string nullable: true callTypeID: type: integer format: int32 nullable: true callType: type: string nullable: true productTypeID: type: integer format: int32 nullable: true productType: type: string nullable: true contract: type: string nullable: true priority: type: integer format: int32 nullable: true notes: type: string nullable: true survey: type: string nullable: true isExchange: type: boolean nullable: true isSuspended: type: boolean nullable: true isFollowUpCompleted: type: boolean nullable: true followUpRequestedDate: type: string format: date-time nullable: true followUpCompletedDate: type: string format: date-time nullable: true suspendedUntilDate: type: string format: date-time nullable: true createdByUser: minLength: 1 type: string createdDate: type: string format: date-time lastUpdatedDate: type: string format: date-time callTime: type: string format: date-time nullable: true callerName: type: string nullable: true phoneFaxNum: type: string nullable: true reference: type: string nullable: true isWatchOne: type: boolean nullable: true isWatchTwo: type: boolean nullable: true transactionTypeID: type: integer format: int32 nullable: true transactionType: type: string nullable: true isEscalated: type: boolean nullable: true initiatedDate: type: string format: date-time nullable: true completeInOrion: type: boolean nullable: true isWatchThree: type: boolean nullable: true transactionAmount: type: number format: double nullable: true sessionID: type: string nullable: true authStatus: type: string nullable: true dob: type: string format: date-time nullable: true ssn: type: string nullable: true callSummary: type: string nullable: true callSummaryDate: type: string format: date-time nullable: true documentNumber: type: string nullable: true callId: type: string nullable: true contracts: type: array items: $ref: "#/components/schemas/CallEntryContract" nullable: true additionalProperties: false Response: type: object properties: message: type: string nullable: true additionalProperties: false CallEntryWriteContractRequest: required: - contractNumber type: object properties: contractNumber: maxLength: 50 minLength: 1 pattern: ^[A-Za-z0-9,-]+$ type: string description: Trimmed contract number, unique case-insensitively within the request. callTypes: type: array items: maxLength: 50 minLength: 1 pattern: ^[A-Za-z0-9 &'/-]+$ type: string description: Explicit active call-type names. Duplicate canonical values within a contract are rejected. nullable: true additionalProperties: false CallEntryContract: required: - callTypes - contractNumber type: object properties: contractNumber: minLength: 1 type: string callTypes: type: array items: type: string additionalProperties: false securitySchemes: Bearer: type: http description: Supply an OAuth bearer token obtained from Auth0. scheme: bearer bearerFormat: JWT ```