CRM lookup cookbook

Use an application API key in Authorization: Bearer YOUR_API_KEY. Pass the central organisation UUID in X-AutoAppy-Workspace. Writes require a read/write key. Never embed a key in frontend source.

First call GET /api/auth/me. The response data.local_workspace_id is the local workspace ID; it is different from the central organisation ID. Use it in workspace paths and X-Workspace-ID.

Pipeline → stage → lead → assigned owner

- GET /admin/pipelines/pipelines: available pipelines, response data with id and name.

- GET /admin/pipelines/stages?pipeline_id=PIPELINE: stages for that pipeline; data[].id is the stage ID.

- GET /workspaces/LOCAL_WORKSPACE/lead-fields?pipeline_id=PIPELINE: available custom columns; use their keys, types and options to construct custom_fields.

- GET /workspaces/LOCAL_WORKSPACE/users: users visible to the caller. Select data[].user_id, not the workspace membership id; data[].user.name is the dropdown label.

- GET /leads?pipeline_id=PIPELINE&search=Raj&page=1&per_page=50: find leads within the selected pipeline. search matches the controller's standard lead search; custom fields use custom_filters.

curl --get 'https://crmapi.autoappy.com/leads' \

 -H 'Authorization: Bearer YOUR_API_KEY' \

 -H 'X-AutoAppy-Workspace: CENTRAL_ORG' -H 'X-Workspace-ID: LOCAL_WORKSPACE' \

 --data-urlencode 'pipeline_id=PIPELINE' --data-urlencode 'search=Raj' --data-urlencode 'per_page=50'

The paginated resource response has data (lead records), links and meta. Use meta.last_page and the next page to continue. Each lead includes id, name and available lead fields. Empty data means no visible matches. Access remains limited to the caller's authorised leads/team.

Create a lead with POST /leads: {"name":"Raj","lead_stage_id":1,"email":"raj@example.com","assigned_user_id":"USER_UUID","custom_fields":{}}. Stage IDs are numeric; pipeline and user IDs are UUIDs. Use the current pipeline schema for custom fields. PUT /leads/{lead} updates the selected lead. IDs in examples are placeholders—look them up first.

pipeline_id, lead_stage_id, assigned_user_id, search, page and per_page are optional filters. Per-page maximum is 100. Invalid pipeline or custom field returns 422. Inaccessible lead returns 403/404. Use a read/write key for create/update; a read-only key may successfully populate every dropdown and still be denied on a write.

General errors and pagination

All example IDs are placeholders. Look them up using your own authorised connection. 401 requires renewed authentication; 403 requires checking application, read/write permissions and workspace; 404 means unavailable resource; 422 contains invalid-field details; 429 requires respecting Retry-After. Dropdowns display the current API page; Map Data accepts an exact identifier from a later page or previous action. Lists never broaden permissions to fill choices.

Save a second form on the original lead

Use POST /leads/enrich with the exact original enquiry reference or lead ID. This fills missing values; it does not create another lead or replace a salesperson's saved answers.

{"intake_event_key":"website:1518","revenue":"100000","additional_details":[{"key":"WhatsApp setup","value":"Business app"},{"key":"Goals","value":"Follow-ups"}]}

A successful response includes the existing data.id and enrichment.updated_fields, preserved_fields, and changed. Retrying the same enrichment produces no further change. Do not send both identifiers. HTTP 409 means the first enquiry has not created its lead; repair or finish that intake before retrying. HTTP 403 means the caller cannot edit this lead; HTTP 404 means it is absent in this workspace; HTTP 422 reports invalid fields. Do not send another Create lead request with changed details under the original idempotency key.