Send work email code

POST/v1/activation/work-email:send-code

Idempotency-Key requiredAccepts bearer

E-mail a code to a work address the Owner must prove before going live — CAPPED flow only

The work-e-mail guardrail of the CAPPED flow, for every CAPPED BUSINESS tenant with no exception: when the sign-up e-mail is on a free-mail domain, or not on the domain of the profile's website, ActivationState.workEmail required is true and the Owner proves a work address before going live (POST /v1/activation:go-live is 409 CONFLICT details.reason WORK_EMAIL_REQUIRED until then). This sends a 6-digit code to email; POST /v1/activation/work-email:confirm proves it. The code lives 15 minutes and allows at most 5 attempts, and a new code voids the previous one, as the terms code; sentTo is the address masked as TermsCodeSent; resendAfter is 60 seconds after the send. Rate limited per Owner as the identity code routes (IdentityRateLimited): 429 RATE_LIMITED details.reason SUBJECT_RATE_LIMITED, details.action work-email-code-send, with Retry-After. On the NINE_STEP flow 409 CONFLICT details.reason FLOW_NOT_CAPPED. Human session only; Owner only (403 PERMISSION_DENIED details.reason OWNER_ONLY). Idempotency-Key required: a replay answers the first 202 and sends nothing. A deployment without an identity mail sender is 501 NOT_IMPLEMENTED details.reason NO_VERIFICATION_SENDER. The code is never logged, audited or returned; the send is audited as activation.work_email_code_sent with sentTo masked. Test mode (the sandbox twin and sandbox keys) is unaffected by the guardrail.

Headers

Idempotency-KeystringRequired
Mandatory on mutations: **48h TTL**; replay with same body-hash returns the original response with Idempotency-Replayed true; same key + different body is 409 IDEMPOTENCY_CONFLICT; in-flight duplicate…Show more
Mandatory on mutations: **48h TTL**; replay with same body-hash returns the original response with Idempotency-Replayed true; same key + different body is 409 IDEMPOTENCY_CONFLICT; in-flight duplicate is 409 IDEMPOTENCY_IN_PROGRESS.

Request bodyWorkEmailSendCodeRequest

emailstring · emailRequired

Responses

202Accepted — a code is on its way to the work addressWorkEmailCodeSent
400VALIDATION details.field email — FREE_MAIL_DOMAIN (a free-mail domain), DOMAIN_NOT_COMPANY (not on the website's domain), or not an e-mail addressApiErrorResponse
401
UNAUTHENTICATED — missing or expired token.Show more
UNAUTHENTICATED — missing or expired token. Declared on every operation because `security` is declared globally at the document root: every route is authenticated, so every route can answer 401.
ApiErrorResponse
403ApiErrorResponse
405
VALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge).Show more
VALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge). Not retryable as sent.
ApiErrorResponse
409CONFLICT FLOW_NOT_CAPPED — the tenant is on the nine-step rail; or IDEMPOTENCY_CONFLICTApiErrorResponse
413
VALIDATION — the request body is larger than the surface's limit.Show more
VALIDATION — the request body is larger than the surface's limit. Not retryable as sent: shrink the body. Declared on every operation that takes a request body. details carries exactly one key, maxBodyBytes (integer): the limit that applies to this surface, in bytes.
ApiErrorResponse
414
VALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge).Show more
VALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge). Not retryable as sent: send long input in the body of a POST.
ApiErrorResponse
415
VALIDATION — a request body that is not JSON (application/json or application/*+json; a form body only on the OAuth token routes).Show more
VALIDATION — a request body that is not JSON (application/json or application/*+json; a form body only on the OAuth token routes). The public edge refuses it before the platform sees it (details.reason UNSUPPORTED_MEDIA_TYPE, details.source edge). Not retryable as sent: send Content-Type application/json. Declared on every operation that takes a JSON request body.
ApiErrorResponse
429RATE_LIMITED SUBJECT_RATE_LIMITED (action work-email-code-send) — too soon after the last code, or too many codesApiErrorResponse
500INTERNAL — a bug, and traceId is the support handle.ApiErrorResponse
501Not retryable.ApiErrorResponse

Errors you should handle

Branch on code and honour retryable — never on the HTTP status alone.

400	VALIDATION Use an address on your company's domain, not a free-mail address.	not retryable
401	UNAUTHENTICATED The bearer token is expired. Re-authenticate and retry.	not retryable
403	PERMISSION_DENIED Reading wallets needs the finance:read permission.	not retryable
405	VALIDATION This method is not served.	not retryable
409	CONFLICT This tenant is on the nine-step activation; no work e-mail check is asked there.	not retryable
409	IDEMPOTENCY_CONFLICT Idempotency-Key 7f0c33d1-9a1e-4d2c-9f77-1c0f2b3a4d55 was used with a different body; never executed	not retryable
413	VALIDATION The request body is larger than this API accepts (262144 bytes).	not retryable
414	VALIDATION The request URI is longer than 8 KiB.	not retryable
415	VALIDATION Send application/json.	not retryable
429	RATE_LIMITED A code was sent a moment ago. Wait for the Retry-After interval before asking for another.	retryable
500	INTERNAL An unexpected error occurred. Quote the traceId to support.	retryable
501	NOT_IMPLEMENTED The capped activation flow is not available on this deployment.	not retryable