Skip to main content
POST
Create a customer in the organization's directory
Creates a customer in the organization’s directory, exactly as the Console does. Send name and customerType (org or user), and optionally primaryEmail, primaryPhone, website, externalIds, metadata and workosId. The body is strict: an unknown field or an empty string is 400 bad_request. Without workosId, Forge first provisions the customer in WorkOS: a WorkOS organization for org, or a WorkOS user for user, created with primaryEmail (or a Forge placeholder address when none is given). It then records the customer; if recording fails, the WorkOS entity it provisioned is deleted. With workosId, Forge provisions nothing: a customer already recorded with that WorkOS id is returned unchanged with created: false, and otherwise a new customer is recorded with it. An active organization customer gets its organization home, as in the Console. An unexpected failure, such as WorkOS being unavailable while an organization is provisioned, is 500 internal_error; every directory route declares it. The credential needs both the customers:read and customers:manage scopes, and customers:read and customers:manage granted at the deployment root; otherwise 403 permission_denied names the missing permission and nothing is provisioned. Success is 201 with {customer, created}. Send an Idempotency-Key: a same-key retry within 24 hours returns the recorded 201 and provisions nothing, while the caller still holds both permissions at the deployment root; a recorded refusal or failure, or a caller that lost that authority, gets 409 idempotency_result_unavailable, and nothing runs again. A retry without a key runs again and, without workosId, provisions another WorkOS identity. When a request’s outcome is unknown, repeat it with the same key first (409 idempotency_key_in_flight while the first attempt is still running). Only after Forge answers idempotency_outcome_unknown or idempotency_result_unavailable, check List customers and use a new key if the customer was not created.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

1–255 printable ASCII characters (0x21–0x7E, no spaces), scoped to the calling credential. A repeat with the same key and request never runs the write again, a 5xx included: once the operation's permissions pass again it answers the identical status and body of the first response (Idempotent-Replayed: true, also sent as Idempotency-Replayed: true), unless the operation's own replay policy withholds it; a first response that was not stored (over 32 KiB, or carrying a one-time secret) answers its first status with only data.id (Idempotency-Replay-Disclosure: id-only) when it named one; otherwise 409 idempotency_result_unavailable; a repeat while the first is still running is 409 idempotency_key_in_flight, and the same key with a different request is 422 idempotency_key_reuse. Honoured for External App JWTs and platform and Personal keys; an External App's static companion key is not protected.

Required string length: 1 - 255

Body

application/json
name
string
required
Minimum string length: 1
customerType
enum<string>
required

org for businesses and organizations, user for individuals.

Available options:
org,
user
primaryEmail
string

For an individual, the email its WorkOS user is created with; without one, Forge uses a placeholder address.

Minimum string length: 1
primaryPhone
string
Minimum string length: 1
website
string
Minimum string length: 1
externalIds
any

CRM dedup anchors, e.g. {hubspot: "123"}.

metadata
any
workosId
string

An existing WorkOS organization or user id. Forge then provisions nothing and returns the customer already recorded with it, if any.

Minimum string length: 1

Response

The customer: created, or already recorded with the supplied workosId (created: false)

data
object
required
meta
object
required