API Keys

An API key lets your website’s server submit consultation requests into REV23. Each accepted submission creates a new customer and an idea for your team to review, and your team continues the workflow in REV23.

Public API keys can only submit an idea intake through one endpoint. There is no permission picker, and a key’s access cannot be widened.

How it works

Your website collects your own consultation questions, in your own design. When a visitor submits the form, your server sends the submission to REV23 with your API key. REV23 creates a new customer with the contact details provided and an idea holding the request and any reference images.

Every submission creates a new customer — intake never searches, matches, or updates existing customers. A public form can’t prove the visitor is who they claim to be, so it isn’t allowed to modify an established profile. If a regular submits twice, you’ll see two customer records; review and tidy them in REV23.

The API key must stay on your server. Never put it in browser JavaScript, a mobile app, or anything else delivered to a visitor.

Creating an API key

API keys live at Settings → Integrations → API Keys. Managing them is owner-only — no role grants it (see Roles & Permissions). Create a new key by providing:

Name — A display name to help you identify this key (e.g., “Website Consult Form”).
Expiration date — Optional. Leave blank for a key that never expires.

After creation, the full key is displayed. This is the only time the key is shown. Copy and store it securely — it cannot be retrieved again. Keys start with rev23_e_, and you can identify a key later by its prefix (the first 12 characters shown in the key list).

The API Keys page also shows your studio ID and a live request reference generated from the current API.

Making requests

Every request requires three headers:

Header	Description
`X-Api-Key`	Your API key
`X-Tenant-Name`	Your Cloud name — the subdomain of your Cloud’s address. For `mystudio.rev23.com`, use `mystudio`
`Idempotency-Key`	A unique ID you generate for each submission (a UUID works well)

Idempotency

The Idempotency-Key header is your retry protection. If your request times out and you send it again with the same key, REV23 returns the original receipt instead of creating a second customer and idea. Generate a new key for each new submission — even if the name and contact details are identical — and reuse a key only to retry the same one.

The intake endpoint

POST https://cloudappapi.rev23.com/api/v2/idea-intakes

The request is multipart/form-data with two parts:

data (required) — The submission as JSON, described below.
files (optional, repeatable) — Reference images attached to the idea. JPEG, PNG, GIF, or WebP; at most 10 files, 6 MB each. The whole request is capped at 61 MB.

The `data` JSON

Field	Required	Description
`studioId`	Yes	The public ID of the studio receiving the request (shown on your API Keys page)
`customer`	Yes	Contact details for the new customer — see below
`description`	Yes	What the customer wants, up to 2,048 characters
`placement`	No	Body placement, up to 128 characters
`size`, `style`, `colorPreference`	No	Up to 128 characters each
`budgetMin`, `budgetMax`	No	Budget range; `budgetMax` must be at least `budgetMin`
`availableMornings`, `availableAfternoons`, `availableEvenings`	See note	Booleans; at least one must be `true`
`availableWeekdays`, `availableWeekends`	See note	Booleans; at least one must be `true`
`availability`	No	Free-text availability notes, up to 256 characters
`preferredDateStart`, `preferredDateEnd`	No	`YYYY-MM-DD`; end must be on or after start
`workType`	No	`New`, `Continuation`, `TouchUp`, or `CoverUp`
`serviceCategoryType`	No	`Tattoo`, `Piercing`, `PermanentMakeup`, `Microblading`, `Removal`, or `Adornment`
`isNewToService`	No	Boolean — first tattoo/piercing?
`userId`	No	Public ID of the requested team member; omit for no preference

The customer object:

Field	Required	Description
`givenName`	Yes	First name, up to 256 characters
`preferredName`, `familyName`	No	Up to 256 characters each
`email`	See note	Email address
`phoneNumber`	See note	Phone number
`birthdate`	No	`YYYY-MM-DD`, not in the future
`emailOptIn`, `smsOptIn`	No	Marketing opt-in booleans

At least one of email or phoneNumber is required — your team needs a way to reach the customer.

Your form doesn’t have to mirror this contract. Skip the optional fields you don’t care about, and if you ask questions the contract has no field for, append those answers to the end of description with clear labels — your team reads it on the idea. Just keep the combined text within the 2,048-character limit.

Example

curl -X POST "https://cloudappapi.rev23.com/api/v2/idea-intakes" \
  -H "X-Api-Key: rev23_e_a1b2c3d4..." \
  -H "X-Tenant-Name: mystudio" \
  -H "Idempotency-Key: 0d6f3c2a-4b1e-4f7a-9c8d-2e5b7a1c9f04" \
  -F 'data={"studioId":"<your-studio-id>","customer":{"givenName":"Jordan","familyName":"Lee","email":"jordan@example.com","emailOptIn":true},"description":"Blackwork floral half sleeve with room to extend later.","placement":"Left upper arm","budgetMin":600,"budgetMax":1000,"availableAfternoons":true,"availableWeekends":true,"workType":"New","serviceCategoryType":"Tattoo"};type=application/json' \
  -F "files=@reference-1.jpg"

A successful submission returns a minimal receipt — the new idea’s ID and the submission timestamp:

{
  "ideaId": "idea_example123",
  "submittedOnUtc": "2026-08-03T16:00:00Z"
}

Response codes

Status	Meaning
`201`	Created — returns the receipt above
`400`	The body or required `Idempotency-Key` is invalid
`401`	The API key is missing or invalid
`403`	The key is not allowed to submit an idea
`409`	A request with this idempotency key is still processing
`413`	The request exceeds the 61 MB body limit
`422`	The idempotency key was reused with a different body
`429`	Rate limited — honor the `Retry-After` header before retrying

Build it with an AI coding agent

Copy the prompt below into your coding agent. Replace <tenant-name> and <studio-id> with the values from your API Keys page. Configure REV23_API_KEY on your server yourself; do not paste the key into an AI conversation.

Add a consultation request form to my website that submits to REV23, the
studio-management software we use. Follow this integration contract exactly.

What to build:

1. Add a consultation form that matches my site's existing design. Collect the
   customer's name, email and/or phone, a description of the work they want,
   placement, budget range, availability, and optional reference images. Ask me
   which optional questions to keep. If I want to collect details that have no
   matching field below, append those answers to `description` with labels and
   keep the combined value within 2,048 characters.
2. Add a server-side handler that submits the form to REV23. The browser must
   never call REV23 directly, and the API key must never reach client-side code.

REV23 request contract:

- Endpoint: POST https://cloudappapi.rev23.com/api/v2/idea-intakes
- Headers:
  - X-Api-Key: Read this from the REV23_API_KEY server environment variable.
    Never hardcode or log it. I will configure it myself.
  - X-Tenant-Name: <tenant-name>
  - Idempotency-Key: Generate a new UUID for each submission. Reuse that UUID
    only when retrying the same submission.
- Body: multipart/form-data with a required `data` part containing JSON with
  content type application/json. Optional reference images use repeated `files`
  parts. Accept JPEG, PNG, GIF, or WebP, with at most 10 files, 6 MB per file,
  and 61 MB for the complete request.
- The `data` JSON contains:
  - studioId: "<studio-id>" (required)
  - customer (required): givenName (required, up to 256 characters);
    preferredName and familyName (optional, up to 256 characters each); email
    and/or phoneNumber (at least one required); birthdate (optional, YYYY-MM-DD,
    not in the future); emailOptIn and smsOptIn (optional booleans)
  - description (required, up to 2,048 characters)
  - placement, size, style, and colorPreference (optional, up to 128 characters
    each)
  - budgetMin and budgetMax (optional; budgetMax must be at least budgetMin)
  - availableMornings, availableAfternoons, and availableEvenings (booleans;
    at least one must be true)
  - availableWeekdays and availableWeekends (booleans; at least one must be
    true)
  - availability (optional free text, up to 256 characters)
  - preferredDateStart and preferredDateEnd (optional, YYYY-MM-DD; the end date
    must be on or after the start date)
  - workType (optional): New | Continuation | TouchUp | CoverUp
  - serviceCategoryType (optional): Tattoo | Piercing | PermanentMakeup |
    Microblading | Removal | Adornment
  - isNewToService (optional boolean)
  - userId (optional): the public ID of the requested team member; omit it when
    the customer has no preference
- Responses:
  - 201: Return value is { ideaId, submittedOnUtc }.
  - 400: Invalid body or missing Idempotency-Key.
  - 401: Missing or invalid API key.
  - 403: The key cannot submit an idea.
  - 409: A request with the same idempotency key is still processing.
  - 413: The request exceeds the body limit.
  - 422: The idempotency key was reused with a different body.
  - 429: Rate limited. Honor the Retry-After header before retrying.

Implementation rules:

- This API key can call only the idea-intake endpoint. Do not call any other
  REV23 endpoint.
- Every accepted submission creates a new customer and idea. Do not add
  customer lookup, matching, deduplication, or update logic.
- Do not poll REV23 or add read or synchronization features.
- Validate required fields on the server before submitting the request.
- After a 201 response, confirm that the request was received. For failures,
  show a message that does not expose REV23 error details.

Developer status

API-key access is an early developer feature. Rate limits, quotas, and schemas may change as REV23 evolves. REV23 does not provide development or troubleshooting services for custom application code.

For integrations beyond custom intake, contact REV23 before beginning development. An endpoint appearing elsewhere in the API is not part of the supported API-key contract.

Managing keys

You can manage your API keys from the same settings page where you created them.

Deactivate a key to temporarily stop it from working without deleting it. You can reactivate it later.
Delete a key to permanently revoke access.

Security best practices

Store keys securely. Treat API keys like passwords. Do not commit them to source control or expose them in client-side code.
Use server-to-server requests only. Never embed an API key in browser JavaScript, a mobile app, a public form, or code delivered to a website visitor.
Do not give keys to AI providers. If AI helps process an intake, keep all REV23 calls on your trusted server.
Set expiration dates for keys used in temporary or time-limited integrations.
Rotate keys periodically. Create a new key, update your integration, then delete the old one.
Deactivate unused keys rather than leaving them active indefinitely.