Add Sub-Account User

Invite a user to any sub-account in your agency with a specified role.

Add Sub-Account User

Invite a user to any sub-account that belongs to your agency. Creates an invitation, sends the email via your agency’s Resend config, and returns a confirmation.

Idempotent refresh: If an unaccepted invitation already exists for the same email + sub_account_id, the existing invitation is refreshed (new token, new 7-day expiry, role/name updated) rather than duplicated.

Endpoint

POST https://crmwebhook.com/functions/v1/crm-api/add-subaccount-user

Headers

Header	Value	Required
X-API-Key or Authorization	Agency API key (cfy_...)	Required
Content-Type	application/json	Required

Request Body

{
  "email": "user@example.com",
  "role": "sub_account_user",
  "sub_account_id": "8f3b1c4d-1111-2222-3333-444455556666",
  "first_name": "Jane",
  "last_name": "Doe",
  "phone": "+15551234567"
}

Body Parameters

Field	Type	Required	Description
email	string	Required	Email address of the invitee. Stored lowercased.
role	string	Required	One of: sub_account_owner, sub_account_admin, sub_account_user
sub_account_id	string (UUID)	Required	Target sub-account. Must belong to the API key’s organization.
first_name	string	Optional	Used in the invitation email
last_name	string	Optional	Used in the invitation email
phone	string	Optional	Stored on the invitation row

Allowed Roles

Value	Display Name
sub_account_owner	Account Owner
sub_account_admin	Account Admin
sub_account_user	Account User

Example — Minimal

curl -X POST https://crmwebhook.com/functions/v1/crm-api/add-subaccount-user \
  -H "X-API-Key: cfy_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "role": "sub_account_user",
    "sub_account_id": "8f3b1c4d-1111-2222-3333-444455556666"
  }'

Example — With name and phone

curl -X POST https://crmwebhook.com/functions/v1/crm-api/add-subaccount-user \
  -H "X-API-Key: cfy_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "role": "sub_account_admin",
    "sub_account_id": "8f3b1c4d-1111-2222-3333-444455556666",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+15551234567"
  }'

Response Shape

{
  "message": "Invitation is sent to user@example.com"
}

Response Codes

Status	Meaning
201	Invitation created and email sent
400	Missing required field, invalid email format, or invalid role
401	Missing or invalid API key
403	Sub-account belongs to a different organization, or user limit reached
404	Sub-account ID not found
502	Invitation created but email failed to send (invitation token still returned for retry)