{ "variable": [ { "id": "baseUrl", "key": "baseUrl", "type": "string", "name": "string", "value": "https:\/\/{your-subdomain}.saleskey.ai" } ], "info": { "name": "SalesKey API Documentation", "_postman_id": "b8002777-09fc-4daa-a93b-f96d1cf9bfea", "description": "Programmatically manage your CRM via the SalesKey REST API.", "schema": "https:\/\/schema.getpostman.com\/json\/collection\/v2.1.0\/collection.json" }, "item": [ { "name": "Leads", "description": "\nProgrammatic access to your CRM Leads. All endpoints require a Bearer API key\nwith the appropriate `leads` permission and a Professional-plan account.", "item": [ { "name": "List leads", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/leads", "query": [ { "key": "page", "value": "1", "description": "Page number.", "disabled": false }, { "key": "per_page", "value": "25", "description": "Results per page (default 25, max 200 - values above 200 are clamped).", "disabled": false }, { "key": "all", "value": "1", "description": "When true, returns leads of every status - including archived and converted - and ignores `status_id` if also sent.", "disabled": false }, { "key": "status_id[0]", "value": "1", "description": "Filter by status ID(s) (see GET \/statuses).", "disabled": false }, { "key": "status_id[1]", "value": "2", "description": "Filter by status ID(s) (see GET \/statuses).", "disabled": false }, { "key": "archived", "value": "", "description": "Include archived leads instead of excluding them (the default).", "disabled": true }, { "key": "converted", "value": "", "description": "Include converted leads instead of excluding them (the default).", "disabled": true }, { "key": "person_id[0]", "value": "9", "description": "Filter by linked Person ID(s).", "disabled": false }, { "key": "organization_id[0]", "value": "4", "description": "Filter by linked Organization ID(s).", "disabled": false }, { "key": "owner_id[0]", "value": "1", "description": "Filter by owner user ID(s).", "disabled": false }, { "key": "assignees[0]", "value": "1", "description": "Filter by assigned user ID(s).", "disabled": false }, { "key": "followers[0]", "value": "1", "description": "Filter by following user ID(s).", "disabled": false }, { "key": "source_channel_id[0]", "value": "1", "description": "Filter by Source Channel ID(s) (see GET \/source-channels).", "disabled": false }, { "key": "labels[0]", "value": "1", "description": "Filter by Label ID(s) (see GET \/labels?type=lead).", "disabled": false }, { "key": "created_by[0]", "value": "1", "description": "Filter by creator user ID(s).", "disabled": false }, { "key": "title", "value": "Acme", "description": "Partial, case-insensitive match on the lead title.", "disabled": false }, { "key": "currency[0]", "value": "USD", "description": "Filter by ISO 4217 currency code(s).", "disabled": false }, { "key": "value_in_base_currency", "value": "0", "description": "numeric[] `[min]` for a lower bound, or `[min,max]` for a range, on value converted to the account's base currency.", "disabled": true }, { "key": "expected_close_date[0]", "value": "2026-09-01", "description": "`[date]` for an exact day, or `[start,end]` for a range (Y-m-d).", "disabled": false }, { "key": "created_at[0]", "value": "2026-01-01", "description": "`[date]` for an exact day, or `[start,end]` for a range (Y-m-d).", "disabled": false }, { "key": "created_at[1]", "value": "2026-08-01", "description": "`[date]` for an exact day, or `[start,end]` for a range (Y-m-d).", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/leads?page=1&per_page=25&all=1&status_id%5B0%5D=1&status_id%5B1%5D=2&archived=&converted=&person_id%5B0%5D=9&organization_id%5B0%5D=4&owner_id%5B0%5D=1&assignees%5B0%5D=1&followers%5B0%5D=1&source_channel_id%5B0%5D=1&labels%5B0%5D=1&created_by%5B0%5D=1&title=Acme¤cy%5B0%5D=USD&value_in_base_currency=0&expected_close_date%5B0%5D=2026-09-01&created_at%5B0%5D=2026-01-01&created_at%5B1%5D=2026-08-01" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns a paginated list of leads, filterable by any combination of the\nparams below. Filters accepting an array (`param[]=`) are OR'd together\nwithin the same param and AND'd with every other param. Any param not\nlisted here - including its singular form like `status` or `person` -\nis silently ignored, not applied.\n\nCustom fields (tenant-specific, configured under Settings > Fields) are\nalso filterable by their slug, e.g. `region=Asia` does a partial match;\nappend `_gte`\/`_lte` to a numeric or date custom field for range\nfiltering, e.g. `budget_gte=1000`. This suffix behavior only applies to\ncustom fields, not the native params below." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":42,\"title\":\"Acme Corp renewal\",\"value\":\"5000.00\",\"currency\":\"USD\",\"value_in_base_currency\":\"5000.00\",\"expected_close_date\":\"2026-09-01\",\"status\":{\"id\":1,\"name\":\"New\",\"slug\":\"lead-new\"},\"person\":{\"id\":9,\"name\":\"John Doe\"},\"organization\":{\"id\":4,\"name\":\"Acme Corp\"},\"owner\":{\"id\":1,\"name\":\"Jane Owner\"},\"source_channel\":\"Referral\",\"source_channel_id\":1,\"exchange_rate\":null,\"labels\":[{\"id\":1,\"name\":\"Hot\"}],\"assignees\":[{\"id\":1,\"name\":\"Jane Owner\"}],\"followers\":[{\"id\":1,\"name\":\"Jane Owner\"}],\"creator\":{\"id\":1,\"name\":\"Jane Owner\"},\"custom_fields\":{\"region\":\"Asia\"},\"created_at\":\"2026-08-06T12:11:37+00:00\",\"updated_at\":\"2026-08-11T06:18:26+00:00\"}],\"links\":{\"first\":\"https:\/\/{your-subdomain}.saleskey.ai\/api\/v1\/leads?per_page=25&page=1\",\"last\":\"https:\/\/{your-subdomain}.saleskey.ai\/api\/v1\/leads?per_page=25&page=1\",\"prev\":null,\"next\":null},\"meta\":{\"current_page\":1,\"from\":1,\"last_page\":1,\"per_page\":25,\"to\":1,\"total\":1,\"path\":\"https:\/\/{your-subdomain}.saleskey.ai\/api\/v1\/leads\",\"links\":[{\"url\":null,\"label\":\"\u00ab Previous\",\"page\":null,\"active\":false},{\"url\":\"https:\/\/{your-subdomain}.saleskey.ai\/api\/v1\/leads?per_page=25&page=1\",\"label\":\"1\",\"page\":1,\"active\":true},{\"url\":null,\"label\":\"Next \u00bb\",\"page\":null,\"active\":false}]}}", "name": "" }, { "header": [], "code": 401, "body": "{\"error\":{\"code\":\"invalid_api_key\",\"message\":\"A valid API key is required.\"}}", "name": "Missing or invalid key" }, { "header": [], "code": 403, "body": "{\"error\":{\"code\":\"plan_upgrade_required\",\"message\":\"The REST API is only available on the Professional plan. Please upgrade to continue.\"}}", "name": "Not on Professional plan" }, { "header": [], "code": 403, "body": "{\"error\":{\"code\":\"insufficient_permissions\",\"message\":\"This API key does not have 'read' permission for 'leads'.\"}}", "name": "Key lacks permission" }, { "header": [], "code": 429, "body": "{\"error\":{\"code\":\"rate_limit_exceeded\",\"message\":\"Too many requests. Please retry later.\",\"retry_after\":42}}", "name": "Rate limited" } ] }, { "name": "Retrieve a lead", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/leads\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/leads\/:id", "variable": [ { "id": "id", "key": "id", "value": 42, "description": "The lead ID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":42,\"title\":\"Acme Corp renewal\",\"value\":\"5000.00\",\"currency\":\"USD\",\"value_in_base_currency\":\"5000.00\",\"expected_close_date\":\"2026-09-01\",\"status\":{\"id\":1,\"name\":\"New\",\"slug\":\"lead-new\"},\"person\":{\"id\":9,\"name\":\"John Doe\"},\"organization\":{\"id\":4,\"name\":\"Acme Corp\"},\"owner\":{\"id\":1,\"name\":\"Jane Owner\"},\"source_channel\":\"Referral\",\"source_channel_id\":1,\"exchange_rate\":null,\"labels\":[{\"id\":1,\"name\":\"Hot\"}],\"assignees\":[{\"id\":1,\"name\":\"Jane Owner\"}],\"followers\":[{\"id\":1,\"name\":\"Jane Owner\"}],\"creator\":{\"id\":1,\"name\":\"Jane Owner\"},\"custom_fields\":{\"region\":\"Asia\"},\"created_at\":\"2026-08-06T12:11:37+00:00\",\"updated_at\":\"2026-08-11T06:18:26+00:00\"}}", "name": "" }, { "header": [], "code": 404, "body": "{\"error\":{\"code\":\"not_found\",\"message\":\"Lead not found.\"}}", "name": "Lead not found" } ] }, { "name": "Create a lead", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/leads", "query": [], "raw": "{{baseUrl}}\/api\/v1\/leads" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"title\":\"Acme Corp renewal\",\"value\":5000,\"currency\":\"USD\",\"exchange_rate\":1,\"expected_close_date\":\"2026-09-01\",\"person\":\"John Doe\",\"organization\":\"Acme Corp\",\"status_id\":1,\"source_channel_id\":1,\"source_channel\":\"Referral\",\"owner_id\":1,\"labels\":[1,2],\"assignees\":[1],\"followers\":[1]}" }, "description": "`title` is the only required field. Every other field - person,\norganization, owner, status, source, custom fields - is optional and\nwill be left empty or defaulted (owner defaults to the API key's\ncreator, status defaults to the account's default lead status) if\nomitted.\n\n`person` and `organization` are plain names, not IDs. Each is matched\nagainst existing records by an exact, case-insensitive name match - if\nfound, the lead is linked to that existing record; if not found, a new\nrecord is created with just that name (matching the CRM's built-in\n\"select or create\" behavior). Any other field not listed below is\nstored as a custom field." }, "response": [ { "header": [], "code": 201, "body": "{\"data\":{\"id\":43,\"title\":\"Acme Corp renewal\",\"value\":\"5000.00\",\"currency\":\"USD\",\"value_in_base_currency\":\"5000.00\",\"expected_close_date\":\"2026-09-01\",\"status\":{\"id\":1,\"name\":\"New\",\"slug\":\"lead-new\"},\"person\":{\"id\":9,\"name\":\"John Doe\"},\"organization\":{\"id\":4,\"name\":\"Acme Corp\"},\"owner\":{\"id\":1,\"name\":\"Jane Owner\"},\"source_channel\":null,\"source_channel_id\":null,\"exchange_rate\":null,\"labels\":[],\"assignees\":[],\"followers\":[],\"creator\":{\"id\":1,\"name\":\"Jane Owner\"},\"custom_fields\":null,\"created_at\":\"2026-08-06T12:11:37+00:00\",\"updated_at\":\"2026-08-06T12:11:37+00:00\"}}", "name": "" }, { "header": [], "code": 422, "body": "{\"error\":{\"code\":\"validation_failed\",\"message\":\"The given data was invalid.\",\"details\":{\"title\":[\"The title field is required.\"]}}}", "name": "Validation failed" } ] }, { "name": "Update a lead", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/leads\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/leads\/:id", "variable": [ { "id": "id", "key": "id", "value": 42, "description": "The lead ID." } ] }, "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"title\":\"Acme Corp renewal (updated)\",\"value\":7500,\"currency\":\"USD\",\"exchange_rate\":1,\"expected_close_date\":\"2026-09-01\",\"person\":\"John Doe\",\"organization\":\"Acme Corp\",\"status_id\":1,\"source_channel_id\":1,\"source_channel\":\"Referral\",\"owner_id\":1,\"labels\":[1,2],\"assignees\":[1],\"followers\":[1]}" }, "description": "Partial update - send only the fields you want to change.\n\n`person` and `organization` follow the same match-or-create rule as\ncreate: exact, case-insensitive name match against an existing record,\nor a new record is created if no match exists." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":42,\"title\":\"Acme Corp renewal (updated)\",\"value\":\"7500.00\",\"currency\":\"USD\",\"value_in_base_currency\":\"7500.00\",\"expected_close_date\":\"2026-09-01\",\"status\":{\"id\":1,\"name\":\"New\",\"slug\":\"lead-new\"},\"person\":{\"id\":9,\"name\":\"John Doe\"},\"organization\":{\"id\":4,\"name\":\"Acme Corp\"},\"owner\":{\"id\":1,\"name\":\"Jane Owner\"},\"source_channel\":\"Referral\",\"source_channel_id\":1,\"exchange_rate\":null,\"labels\":[{\"id\":1,\"name\":\"Hot\"}],\"assignees\":[{\"id\":1,\"name\":\"Jane Owner\"}],\"followers\":[{\"id\":1,\"name\":\"Jane Owner\"}],\"creator\":{\"id\":1,\"name\":\"Jane Owner\"},\"custom_fields\":{\"region\":\"Asia\"},\"created_at\":\"2026-08-06T12:11:37+00:00\",\"updated_at\":\"2026-08-11T06:18:26+00:00\"}}", "name": "" }, { "header": [], "code": 404, "body": "{\"error\":{\"code\":\"not_found\",\"message\":\"Lead not found.\"}}", "name": "Lead not found" }, { "header": [], "code": 422, "body": "{\"error\":{\"code\":\"validation_failed\",\"message\":\"The given data was invalid.\",\"details\":{\"title\":[\"The title field must be a string.\"]}}}", "name": "Validation failed" } ] }, { "name": "Delete a lead", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/leads\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/leads\/:id", "variable": [ { "id": "id", "key": "id", "value": 42, "description": "The lead ID." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Soft-deletes the lead, matching the internal delete behavior." }, "response": [ { "header": [], "code": 204, "body": "{}", "name": "" } ] } ] }, { "name": "Deals", "description": "\nProgrammatic access to your CRM Deals. All endpoints require a Bearer API key\nwith the appropriate `deals` permission and a Professional-plan account.", "item": [ { "name": "List deals", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/deals", "query": [ { "key": "page", "value": "1", "description": "Page number.", "disabled": false }, { "key": "per_page", "value": "25", "description": "Results per page (default 25, max 200 - values above 200 are clamped).", "disabled": false }, { "key": "all", "value": "1", "description": "When true, returns deals of every status - including archived and won - and ignores `status_id` if also sent.", "disabled": false }, { "key": "status_id[0]", "value": "15", "description": "Filter by status ID(s) (see GET \/statuses).", "disabled": false }, { "key": "archived", "value": "", "description": "Include archived (and won) deals instead of excluding them (the default).", "disabled": true }, { "key": "pipeline", "value": "1", "description": "Filter by Pipeline ID (see GET \/pipelines).", "disabled": false }, { "key": "person_id[0]", "value": "9", "description": "Filter by linked Person ID(s).", "disabled": false }, { "key": "organization_id[0]", "value": "4", "description": "Filter by linked Organization ID(s).", "disabled": false }, { "key": "owner_id[0]", "value": "1", "description": "Filter by owner user ID(s).", "disabled": false }, { "key": "assignees[0]", "value": "1", "description": "Filter by assigned user ID(s).", "disabled": false }, { "key": "followers[0]", "value": "1", "description": "Filter by following user ID(s).", "disabled": false }, { "key": "source_channel_id[0]", "value": "1", "description": "Filter by Source Channel ID(s) (see GET \/source-channels).", "disabled": false }, { "key": "labels[0]", "value": "1", "description": "Filter by Label ID(s) (see GET \/labels?type=deal).", "disabled": false }, { "key": "created_by[0]", "value": "1", "description": "Filter by creator user ID(s).", "disabled": false }, { "key": "title", "value": "Acme", "description": "Partial, case-insensitive match on the deal title.", "disabled": false }, { "key": "currency[0]", "value": "USD", "description": "Filter by ISO 4217 currency code(s).", "disabled": false }, { "key": "value_in_base_currency", "value": "0", "description": "numeric[] `[min]` for a lower bound, or `[min,max]` for a range, on value converted to the account's base currency.", "disabled": true }, { "key": "expected_close_date[0]", "value": "2026-09-01", "description": "`[date]` for an exact day, or `[start,end]` for a range (Y-m-d).", "disabled": false }, { "key": "created_at[0]", "value": "2026-01-01", "description": "`[date]` for an exact day, or `[start,end]` for a range (Y-m-d).", "disabled": false }, { "key": "created_at[1]", "value": "2026-08-01", "description": "`[date]` for an exact day, or `[start,end]` for a range (Y-m-d).", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/deals?page=1&per_page=25&all=1&status_id%5B0%5D=15&archived=&pipeline=1&person_id%5B0%5D=9&organization_id%5B0%5D=4&owner_id%5B0%5D=1&assignees%5B0%5D=1&followers%5B0%5D=1&source_channel_id%5B0%5D=1&labels%5B0%5D=1&created_by%5B0%5D=1&title=Acme¤cy%5B0%5D=USD&value_in_base_currency=0&expected_close_date%5B0%5D=2026-09-01&created_at%5B0%5D=2026-01-01&created_at%5B1%5D=2026-08-01" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns a paginated list of deals, filterable by any combination of the\nparams below. Filters accepting an array (`param[]=`) are OR'd together\nwithin the same param and AND'd with every other param. Any param not\nlisted here - including its singular form like `status` or `person` -\nis silently ignored, not applied.\n\nCustom fields (tenant-specific, configured under Settings > Fields) are\nalso filterable by their slug, e.g. `country=Qatar` does a partial\nmatch; append `_gte`\/`_lte` to a numeric or date custom field for range\nfiltering, e.g. `budget_gte=1000`. This suffix behavior only applies to\ncustom fields, not the native params below." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":7,\"title\":\"Acme Corp expansion\",\"value\":\"12000.00\",\"currency\":\"USD\",\"value_in_base_currency\":\"12000.00\",\"expected_close_date\":\"2026-09-01\",\"status\":{\"id\":15,\"name\":\"Open\",\"slug\":\"deal-open\"},\"pipeline\":{\"id\":1,\"name\":\"Deal Flow\"},\"pipeline_stage\":{\"id\":1,\"name\":\"Qualified\"},\"closed_reason\":null,\"closed_reason_note\":null,\"person\":{\"id\":9,\"name\":\"John Doe\"},\"organization\":{\"id\":4,\"name\":\"Acme Corp\"},\"owner\":{\"id\":1,\"name\":\"Jane Owner\"},\"source_channel\":\"Referral\",\"source_channel_id\":1,\"exchange_rate\":null,\"labels\":[{\"id\":1,\"name\":\"Hot\"}],\"assignees\":[{\"id\":1,\"name\":\"Jane Owner\"}],\"followers\":[{\"id\":1,\"name\":\"Jane Owner\"}],\"creator\":{\"id\":1,\"name\":\"Jane Owner\"},\"custom_fields\":{\"country\":\"Qatar\"},\"created_at\":\"2026-08-06T11:42:43+00:00\",\"updated_at\":\"2026-08-06T11:43:16+00:00\"}],\"links\":{\"first\":\"https:\/\/{your-subdomain}.saleskey.ai\/api\/v1\/deals?per_page=25&page=1\",\"last\":\"https:\/\/{your-subdomain}.saleskey.ai\/api\/v1\/deals?per_page=25&page=1\",\"prev\":null,\"next\":null},\"meta\":{\"current_page\":1,\"from\":1,\"last_page\":1,\"per_page\":25,\"to\":1,\"total\":1,\"path\":\"https:\/\/{your-subdomain}.saleskey.ai\/api\/v1\/deals\",\"links\":[{\"url\":null,\"label\":\"\u00ab Previous\",\"page\":null,\"active\":false},{\"url\":\"https:\/\/{your-subdomain}.saleskey.ai\/api\/v1\/deals?per_page=25&page=1\",\"label\":\"1\",\"page\":1,\"active\":true},{\"url\":null,\"label\":\"Next \u00bb\",\"page\":null,\"active\":false}]}}", "name": "" }, { "header": [], "code": 401, "body": "{\"error\":{\"code\":\"invalid_api_key\",\"message\":\"A valid API key is required.\"}}", "name": "Missing or invalid key" }, { "header": [], "code": 403, "body": "{\"error\":{\"code\":\"plan_upgrade_required\",\"message\":\"The REST API is only available on the Professional plan. Please upgrade to continue.\"}}", "name": "Not on Professional plan" }, { "header": [], "code": 403, "body": "{\"error\":{\"code\":\"insufficient_permissions\",\"message\":\"This API key does not have 'read' permission for 'deals'.\"}}", "name": "Key lacks permission" }, { "header": [], "code": 429, "body": "{\"error\":{\"code\":\"rate_limit_exceeded\",\"message\":\"Too many requests. Please retry later.\",\"retry_after\":42}}", "name": "Rate limited" } ] }, { "name": "Retrieve a deal", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/deals\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/deals\/:id", "variable": [ { "id": "id", "key": "id", "value": 7, "description": "The deal ID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":7,\"title\":\"Acme Corp expansion\",\"value\":\"12000.00\",\"currency\":\"USD\",\"value_in_base_currency\":\"12000.00\",\"expected_close_date\":\"2026-09-01\",\"status\":{\"id\":15,\"name\":\"Open\",\"slug\":\"deal-open\"},\"pipeline\":{\"id\":1,\"name\":\"Deal Flow\"},\"pipeline_stage\":{\"id\":1,\"name\":\"Qualified\"},\"closed_reason\":null,\"closed_reason_note\":null,\"person\":{\"id\":9,\"name\":\"John Doe\"},\"organization\":{\"id\":4,\"name\":\"Acme Corp\"},\"owner\":{\"id\":1,\"name\":\"Jane Owner\"},\"source_channel\":\"Referral\",\"source_channel_id\":1,\"exchange_rate\":null,\"labels\":[{\"id\":1,\"name\":\"Hot\"}],\"assignees\":[{\"id\":1,\"name\":\"Jane Owner\"}],\"followers\":[{\"id\":1,\"name\":\"Jane Owner\"}],\"creator\":{\"id\":1,\"name\":\"Jane Owner\"},\"custom_fields\":{\"country\":\"Qatar\"},\"created_at\":\"2026-08-06T11:42:43+00:00\",\"updated_at\":\"2026-08-06T11:43:16+00:00\"}}", "name": "" }, { "header": [], "code": 404, "body": "{\"error\":{\"code\":\"not_found\",\"message\":\"Deal not found.\"}}", "name": "Deal not found" } ] }, { "name": "Create a deal", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/deals", "query": [], "raw": "{{baseUrl}}\/api\/v1\/deals" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"title\":\"Acme Corp expansion\",\"value\":12000,\"currency\":\"USD\",\"exchange_rate\":1,\"expected_close_date\":\"2026-09-01\",\"pipeline_id\":1,\"pipeline_stage_id\":3,\"lead_id\":42,\"person\":\"John Doe\",\"organization\":\"Acme Corp\",\"status_id\":1,\"source_channel_id\":1,\"source_channel\":\"Referral\",\"owner_id\":1,\"labels\":[1,2],\"assignees\":[1],\"followers\":[1]}" }, "description": "`title` is the only required field. Every other field is optional.\n`pipeline_id` and `pipeline_stage_id` default independently when\nomitted: a missing `pipeline_id` resolves to the tenant's default\n(first active) pipeline; a missing `pipeline_stage_id` resolves to the\nfirst stage of whichever pipeline was used (the one you passed, or the\ndefault) - so passing `pipeline_id` alone still picks that specific\npipeline's first stage, not the tenant default's.\n\nPass `lead_id` to convert an existing Lead into this Deal - the source\nLead is marked converted, and its linked emails are copied over, exactly\nas when converting a lead from the app itself.\n\n`person` and `organization` are plain names, not IDs. Each is matched\nagainst existing records by an exact, case-insensitive name match. If\nfound, the deal is linked to that existing record; if not found, a new\nrecord is created with just that name. Any other field not listed\nbelow is stored as a custom field." }, "response": [ { "header": [], "code": 201, "body": "{\"data\":{\"id\":8,\"title\":\"Acme Corp expansion\",\"value\":\"12000.00\",\"currency\":\"USD\",\"value_in_base_currency\":\"12000.00\",\"expected_close_date\":null,\"status\":{\"id\":15,\"name\":\"Open\",\"slug\":\"deal-open\"},\"pipeline\":{\"id\":1,\"name\":\"Deal Flow\"},\"pipeline_stage\":{\"id\":1,\"name\":\"Qualified\"},\"closed_reason\":null,\"closed_reason_note\":null,\"person\":{\"id\":9,\"name\":\"John Doe\"},\"organization\":{\"id\":4,\"name\":\"Acme Corp\"},\"owner\":{\"id\":1,\"name\":\"Jane Owner\"},\"source_channel\":null,\"source_channel_id\":null,\"exchange_rate\":null,\"labels\":[],\"assignees\":[],\"followers\":[],\"creator\":{\"id\":1,\"name\":\"Jane Owner\"},\"custom_fields\":null,\"created_at\":\"2026-08-06T11:42:43+00:00\",\"updated_at\":\"2026-08-06T11:42:43+00:00\"}}", "name": "" }, { "header": [], "code": 422, "body": "{\"error\":{\"code\":\"validation_failed\",\"message\":\"The given data was invalid.\",\"details\":{\"title\":[\"The title field is required.\"]}}}", "name": "Validation failed" } ] }, { "name": "Update a deal", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/deals\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/deals\/:id", "variable": [ { "id": "id", "key": "id", "value": 7, "description": "The deal ID." } ] }, "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"title\":\"Acme Corp expansion (updated)\",\"value\":15000,\"currency\":\"USD\",\"exchange_rate\":1,\"person\":\"John Doe\",\"organization\":\"Acme Corp\",\"status_id\":1,\"source_channel_id\":1,\"source_channel\":\"Referral\",\"owner_id\":1,\"labels\":[1,2],\"assignees\":[1],\"followers\":[1]}" }, "description": "Partial update - send only the fields you want to change. Pipeline\nstage cannot be changed here; use the dedicated stage endpoint below.\n\n`person` and `organization` follow the same match-or-create rule as\ncreate: exact, case-insensitive name match against an existing record,\nor a new record is created if no match exists." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":7,\"title\":\"Acme Corp expansion (updated)\",\"value\":\"15000.00\",\"currency\":\"USD\",\"value_in_base_currency\":\"15000.00\",\"expected_close_date\":\"2026-09-01\",\"status\":{\"id\":15,\"name\":\"Open\",\"slug\":\"deal-open\"},\"pipeline\":{\"id\":1,\"name\":\"Deal Flow\"},\"pipeline_stage\":{\"id\":1,\"name\":\"Qualified\"},\"closed_reason\":null,\"closed_reason_note\":null,\"person\":{\"id\":9,\"name\":\"John Doe\"},\"organization\":{\"id\":4,\"name\":\"Acme Corp\"},\"owner\":{\"id\":1,\"name\":\"Jane Owner\"},\"source_channel\":\"Referral\",\"source_channel_id\":1,\"exchange_rate\":null,\"labels\":[{\"id\":1,\"name\":\"Hot\"}],\"assignees\":[{\"id\":1,\"name\":\"Jane Owner\"}],\"followers\":[{\"id\":1,\"name\":\"Jane Owner\"}],\"creator\":{\"id\":1,\"name\":\"Jane Owner\"},\"custom_fields\":{\"country\":\"Qatar\"},\"created_at\":\"2026-08-06T11:42:43+00:00\",\"updated_at\":\"2026-08-11T06:30:44+00:00\"}}", "name": "" }, { "header": [], "code": 404, "body": "{\"error\":{\"code\":\"not_found\",\"message\":\"Deal not found.\"}}", "name": "Deal not found" }, { "header": [], "code": 422, "body": "{\"error\":{\"code\":\"validation_failed\",\"message\":\"The given data was invalid.\",\"details\":{\"pipeline_stage_id\":[\"Stage cannot be changed here - use PATCH \/deals\/{id}\/stage instead.\"]}}}", "name": "Validation failed" } ] }, { "name": "Change a deal's stage", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/deals\/:id\/stage", "query": [], "raw": "{{baseUrl}}\/api\/v1\/deals\/:id\/stage", "variable": [ { "id": "id", "key": "id", "value": 7, "description": "The deal ID." } ] }, "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"pipeline_stage_id\":3,\"pipeline_id\":1}" }, "description": "" }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":7,\"title\":\"Acme Corp expansion\",\"value\":\"12000.00\",\"currency\":\"USD\",\"value_in_base_currency\":\"12000.00\",\"expected_close_date\":\"2026-09-01\",\"status\":{\"id\":15,\"name\":\"Open\",\"slug\":\"deal-open\"},\"pipeline\":{\"id\":1,\"name\":\"Deal Flow\"},\"pipeline_stage\":{\"id\":2,\"name\":\"Contact Made\"},\"closed_reason\":null,\"closed_reason_note\":null,\"person\":{\"id\":9,\"name\":\"John Doe\"},\"organization\":{\"id\":4,\"name\":\"Acme Corp\"},\"owner\":{\"id\":1,\"name\":\"Jane Owner\"},\"source_channel\":\"Referral\",\"source_channel_id\":1,\"exchange_rate\":null,\"labels\":[{\"id\":1,\"name\":\"Hot\"}],\"assignees\":[{\"id\":1,\"name\":\"Jane Owner\"}],\"followers\":[{\"id\":1,\"name\":\"Jane Owner\"}],\"creator\":{\"id\":1,\"name\":\"Jane Owner\"},\"custom_fields\":{\"country\":\"Qatar\"},\"created_at\":\"2026-08-06T11:42:43+00:00\",\"updated_at\":\"2026-08-11T06:31:00+00:00\"}}", "name": "" }, { "header": [], "code": 404, "body": "{\"error\":{\"code\":\"not_found\",\"message\":\"Deal not found.\"}}", "name": "Deal not found" }, { "header": [], "code": 422, "body": "{\"error\":{\"code\":\"validation_failed\",\"message\":\"The given data was invalid.\",\"details\":{\"pipeline_stage_id\":[\"The selected pipeline stage id is invalid.\"]}}}", "name": "Validation failed" } ] }, { "name": "Delete a deal", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/deals\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/deals\/:id", "variable": [ { "id": "id", "key": "id", "value": 7, "description": "The deal ID." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Soft-deletes the deal, matching the internal delete behavior." }, "response": [ { "header": [], "code": 204, "body": "{}", "name": "" } ] } ] }, { "name": "People", "description": "\nProgrammatic access to your CRM People (contacts). All endpoints require a\nBearer API key with the appropriate `people` permission and a\nProfessional-plan account.", "item": [ { "name": "List people", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/people", "query": [ { "key": "page", "value": "1", "description": "Page number.", "disabled": false }, { "key": "per_page", "value": "25", "description": "Results per page (default 25, max 200 - values above 200 are clamped).", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/people?page=1&per_page=25" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns a paginated list of people. Supports `page`, `per_page`, and the\nsame filters as the web app." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":9,\"name\":\"John Doe\",\"first_name\":\"John\",\"last_name\":\"Doe\",\"email\":[{\"label\":\"Work\",\"value\":\"john.doe@example.com\"}],\"phone\":[{\"label\":\"Mobile\",\"value\":\"+17703505963\"}],\"status\":{\"id\":9,\"name\":\"Lead\",\"slug\":\"contact-lead\"},\"organizations\":[{\"id\":4,\"name\":\"Acme Corp\"}],\"custom_fields\":{\"region\":\"Asia\"},\"created_at\":\"2026-08-06T12:11:37+00:00\",\"updated_at\":\"2026-08-06T12:11:37+00:00\"}],\"links\":{\"first\":\"https:\/\/{your-subdomain}.saleskey.ai\/api\/v1\/people?per_page=25&page=1\",\"last\":\"https:\/\/{your-subdomain}.saleskey.ai\/api\/v1\/people?per_page=25&page=1\",\"prev\":null,\"next\":null},\"meta\":{\"current_page\":1,\"from\":1,\"last_page\":1,\"per_page\":25,\"to\":1,\"total\":1,\"path\":\"https:\/\/{your-subdomain}.saleskey.ai\/api\/v1\/people\",\"links\":[{\"url\":null,\"label\":\"\u00ab Previous\",\"page\":null,\"active\":false},{\"url\":\"https:\/\/{your-subdomain}.saleskey.ai\/api\/v1\/people?per_page=25&page=1\",\"label\":\"1\",\"page\":1,\"active\":true},{\"url\":null,\"label\":\"Next \u00bb\",\"page\":null,\"active\":false}]}}", "name": "" }, { "header": [], "code": 401, "body": "{\"error\":{\"code\":\"invalid_api_key\",\"message\":\"A valid API key is required.\"}}", "name": "Missing or invalid key" }, { "header": [], "code": 403, "body": "{\"error\":{\"code\":\"plan_upgrade_required\",\"message\":\"The REST API is only available on the Professional plan. Please upgrade to continue.\"}}", "name": "Not on Professional plan" }, { "header": [], "code": 403, "body": "{\"error\":{\"code\":\"insufficient_permissions\",\"message\":\"This API key does not have 'read' permission for 'people'.\"}}", "name": "Key lacks permission" }, { "header": [], "code": 429, "body": "{\"error\":{\"code\":\"rate_limit_exceeded\",\"message\":\"Too many requests. Please retry later.\",\"retry_after\":42}}", "name": "Rate limited" } ] }, { "name": "Retrieve a person", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/people\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/people\/:id", "variable": [ { "id": "id", "key": "id", "value": 9, "description": "The person ID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":9,\"name\":\"John Doe\",\"first_name\":\"John\",\"last_name\":\"Doe\",\"email\":[{\"label\":\"Work\",\"value\":\"john.doe@example.com\"}],\"phone\":[{\"label\":\"Mobile\",\"value\":\"+17703505963\"}],\"status\":{\"id\":9,\"name\":\"Lead\",\"slug\":\"contact-lead\"},\"organizations\":[{\"id\":4,\"name\":\"Acme Corp\"}],\"custom_fields\":{\"region\":\"Asia\"},\"created_at\":\"2026-08-06T12:11:37+00:00\",\"updated_at\":\"2026-08-06T12:11:37+00:00\"}}", "name": "" }, { "header": [], "code": 404, "body": "{\"error\":{\"code\":\"not_found\",\"message\":\"Person not found.\"}}", "name": "Person not found" } ] }, { "name": "Create a person", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/people", "query": [], "raw": "{{baseUrl}}\/api\/v1\/people" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"name\":\"Jane Doe\",\"organization\":\"Acme Corp\"}" }, "description": "`name` is the only required field. Every other field - email, phone,\nstatus, custom fields - is optional and will be left empty or defaulted\n(status defaults to the account's default contact status) if omitted.\n\nPass `organization` to attach a Person's Organization - a plain name,\nmatched by exact, case-insensitive name against an existing\nOrganization (attached if found), or created if no match exists. A\nPerson's organization is a many-to-many link, not a single field." }, "response": [ { "header": [], "code": 201, "body": "{\"data\":{\"id\":9,\"name\":\"Jane Doe\",\"first_name\":\"Jane\",\"last_name\":\"Doe\",\"email\":null,\"phone\":null,\"status\":{\"id\":9,\"name\":\"Lead\",\"slug\":\"contact-lead\"},\"organizations\":[],\"custom_fields\":null,\"created_at\":\"2026-08-06T12:11:37+00:00\",\"updated_at\":\"2026-08-06T12:11:37+00:00\"}}", "name": "" }, { "header": [], "code": 422, "body": "{\"error\":{\"code\":\"validation_failed\",\"message\":\"The given data was invalid.\",\"details\":{\"name\":[\"The name field is required.\"]}}}", "name": "Validation failed" } ] }, { "name": "Update a person", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/people\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/people\/:id", "variable": [ { "id": "id", "key": "id", "value": 9, "description": "The person ID." } ] }, "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"name\":\"Jane Doe (updated)\",\"organization\":\"Acme Corp\"}" }, "description": "Partial update - send only the fields you want to change. Unlike the\ninternal app's edit form, `organization` can be sent alongside other\nfields in the same request; the organization link is replaced (not\nadded to) when provided. It follows the same match-or-create rule as\ncreate: exact, case-insensitive name match against an existing\nOrganization, or a new one is created if no match exists." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":9,\"name\":\"Jane Doe (updated)\",\"first_name\":\"Jane\",\"last_name\":\"Doe (updated)\",\"email\":null,\"phone\":null,\"status\":{\"id\":9,\"name\":\"Lead\",\"slug\":\"contact-lead\"},\"organizations\":[{\"id\":4,\"name\":\"Acme Corp\"}],\"custom_fields\":null,\"created_at\":\"2026-08-06T09:26:59+00:00\",\"updated_at\":\"2026-08-06T11:46:04+00:00\"}}", "name": "" }, { "header": [], "code": 404, "body": "{\"error\":{\"code\":\"not_found\",\"message\":\"Person not found.\"}}", "name": "Person not found" }, { "header": [], "code": 422, "body": "{\"error\":{\"code\":\"validation_failed\",\"message\":\"The given data was invalid.\",\"details\":{\"name\":[\"The name field must be a string.\"]}}}", "name": "Validation failed" } ] }, { "name": "Delete a person", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/people\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/people\/:id", "variable": [ { "id": "id", "key": "id", "value": 9, "description": "The person ID." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Soft-deletes the person, matching the internal delete behavior." }, "response": [ { "header": [], "code": 204, "body": "{}", "name": "" } ] } ] }, { "name": "Organizations", "description": "\nProgrammatic access to your CRM Organizations. All endpoints require a\nBearer API key with the appropriate `organizations` permission and a\nProfessional-plan account.", "item": [ { "name": "List organizations", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/organizations", "query": [ { "key": "page", "value": "1", "description": "Page number.", "disabled": false }, { "key": "per_page", "value": "25", "description": "Results per page (default 25, max 200 - values above 200 are clamped).", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/organizations?page=1&per_page=25" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns a paginated list of organizations. Supports `page`, `per_page`,\nand the same filters as the web app." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":4,\"name\":\"Acme Corp\",\"email\":\"info@acme.test\",\"phone\":\"+13947741292\",\"website\":\"https:\/\/acme.test\",\"street_address\":\"3944 Broadway\",\"city\":\"Phoenix\",\"state\":\"AZ\",\"postal_code\":\"27434\",\"country\":\"United States\",\"status\":{\"id\":11,\"name\":\"In Deal\",\"slug\":\"contact-in-deal\"},\"people\":[{\"id\":9,\"name\":\"John Doe\"}],\"custom_fields\":{\"industry\":\"SaaS\"},\"created_at\":\"2026-08-05T07:05:52+00:00\",\"updated_at\":\"2026-08-06T11:42:43+00:00\"}],\"links\":{\"first\":\"https:\/\/{your-subdomain}.saleskey.ai\/api\/v1\/organizations?per_page=25&page=1\",\"last\":\"https:\/\/{your-subdomain}.saleskey.ai\/api\/v1\/organizations?per_page=25&page=1\",\"prev\":null,\"next\":null},\"meta\":{\"current_page\":1,\"from\":1,\"last_page\":1,\"per_page\":25,\"to\":1,\"total\":1,\"path\":\"https:\/\/{your-subdomain}.saleskey.ai\/api\/v1\/organizations\",\"links\":[{\"url\":null,\"label\":\"\u00ab Previous\",\"page\":null,\"active\":false},{\"url\":\"https:\/\/{your-subdomain}.saleskey.ai\/api\/v1\/organizations?per_page=25&page=1\",\"label\":\"1\",\"page\":1,\"active\":true},{\"url\":null,\"label\":\"Next \u00bb\",\"page\":null,\"active\":false}]}}", "name": "" }, { "header": [], "code": 401, "body": "{\"error\":{\"code\":\"invalid_api_key\",\"message\":\"A valid API key is required.\"}}", "name": "Missing or invalid key" }, { "header": [], "code": 403, "body": "{\"error\":{\"code\":\"plan_upgrade_required\",\"message\":\"The REST API is only available on the Professional plan. Please upgrade to continue.\"}}", "name": "Not on Professional plan" }, { "header": [], "code": 403, "body": "{\"error\":{\"code\":\"insufficient_permissions\",\"message\":\"This API key does not have 'read' permission for 'organizations'.\"}}", "name": "Key lacks permission" }, { "header": [], "code": 429, "body": "{\"error\":{\"code\":\"rate_limit_exceeded\",\"message\":\"Too many requests. Please retry later.\",\"retry_after\":42}}", "name": "Rate limited" } ] }, { "name": "Retrieve an organization", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/organizations\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/organizations\/:id", "variable": [ { "id": "id", "key": "id", "value": 4, "description": "The organization ID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":4,\"name\":\"Acme Corp\",\"email\":\"info@acme.test\",\"phone\":\"+13947741292\",\"website\":\"https:\/\/acme.test\",\"street_address\":\"3944 Broadway\",\"city\":\"Phoenix\",\"state\":\"AZ\",\"postal_code\":\"27434\",\"country\":\"United States\",\"status\":{\"id\":11,\"name\":\"In Deal\",\"slug\":\"contact-in-deal\"},\"people\":[{\"id\":9,\"name\":\"John Doe\"}],\"custom_fields\":{\"industry\":\"SaaS\"},\"created_at\":\"2026-08-05T07:05:52+00:00\",\"updated_at\":\"2026-08-06T11:42:43+00:00\"}}", "name": "" }, { "header": [], "code": 404, "body": "{\"error\":{\"code\":\"not_found\",\"message\":\"Organization not found.\"}}", "name": "Organization not found" } ] }, { "name": "Create an organization", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/organizations", "query": [], "raw": "{{baseUrl}}\/api\/v1\/organizations" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"name\":\"Acme Corp\",\"website\":\"acme.test\"}" }, "description": "`name` is the only required field. Every other field is optional. Note:\n`status_id` cannot be set on create - it always defaults to the\naccount's default contact status, matching the internal app's existing\nbehavior. To attach people to the organization, use the dedicated\nlink-person endpoint below after creation." }, "response": [ { "header": [], "code": 201, "body": "{\"data\":{\"id\":4,\"name\":\"Acme Corp\",\"email\":null,\"phone\":null,\"website\":\"https:\/\/acme.test\",\"street_address\":null,\"city\":null,\"state\":null,\"postal_code\":null,\"country\":null,\"status\":{\"id\":8,\"name\":\"Record Only\",\"slug\":\"contact-record-only\"},\"people\":[],\"custom_fields\":null,\"created_at\":\"2026-08-06T11:46:31+00:00\",\"updated_at\":\"2026-08-06T11:46:31+00:00\"}}", "name": "" }, { "header": [], "code": 422, "body": "{\"error\":{\"code\":\"validation_failed\",\"message\":\"The given data was invalid.\",\"details\":{\"name\":[\"The name field is required.\"]}}}", "name": "Validation failed" } ] }, { "name": "Update an organization", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/organizations\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/organizations\/:id", "variable": [ { "id": "id", "key": "id", "value": 4, "description": "The organization ID." } ] }, "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"name\":\"Acme Corp (updated)\"}" }, "description": "Partial update - send only the fields you want to change." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":4,\"name\":\"Acme Corp (updated)\",\"email\":\"info@acme.test\",\"phone\":\"+13947741292\",\"website\":\"https:\/\/acme.test\",\"street_address\":\"3944 Broadway\",\"city\":\"Phoenix\",\"state\":\"AZ\",\"postal_code\":\"27434\",\"country\":\"United States\",\"status\":{\"id\":11,\"name\":\"In Deal\",\"slug\":\"contact-in-deal\"},\"people\":[{\"id\":9,\"name\":\"John Doe\"}],\"custom_fields\":{\"industry\":\"SaaS\"},\"created_at\":\"2026-08-05T07:05:52+00:00\",\"updated_at\":\"2026-08-06T11:42:43+00:00\"}}", "name": "" }, { "header": [], "code": 404, "body": "{\"error\":{\"code\":\"not_found\",\"message\":\"Organization not found.\"}}", "name": "Organization not found" }, { "header": [], "code": 422, "body": "{\"error\":{\"code\":\"validation_failed\",\"message\":\"The given data was invalid.\",\"details\":{\"name\":[\"The name field must be a string.\"]}}}", "name": "Validation failed" } ] }, { "name": "Link a person to an organization", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/organizations\/:id\/people", "query": [], "raw": "{{baseUrl}}\/api\/v1\/organizations\/:id\/people", "variable": [ { "id": "id", "key": "id", "value": 4, "description": "The organization ID." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"person\":\"Jane Doe\"}" }, "description": "`person` is a plain name - matched by exact, case-insensitive name\nagainst an existing Person (attached if found), or created and\nattached if no match exists." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":4,\"name\":\"Acme Corp\",\"email\":null,\"phone\":null,\"website\":\"https:\/\/acme.test\",\"street_address\":null,\"city\":null,\"state\":null,\"postal_code\":null,\"country\":null,\"status\":{\"id\":11,\"name\":\"In Deal\",\"slug\":\"contact-in-deal\"},\"people\":[{\"id\":9,\"name\":\"Jane Doe\"}],\"custom_fields\":null,\"created_at\":\"2026-08-05T07:05:52+00:00\",\"updated_at\":\"2026-08-06T11:42:43+00:00\"}}", "name": "" }, { "header": [], "code": 404, "body": "{\"error\":{\"code\":\"not_found\",\"message\":\"Organization not found.\"}}", "name": "Organization not found" } ] }, { "name": "Unlink a person from an organization", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/organizations\/:id\/people\/:personId", "query": [], "raw": "{{baseUrl}}\/api\/v1\/organizations\/:id\/people\/:personId", "variable": [ { "id": "id", "key": "id", "value": 4, "description": "The organization ID." }, { "id": "personId", "key": "personId", "value": 9, "description": "The person ID to unlink." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"person_id\":16}" }, "description": "Detaches the person without deleting the Person record itself." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":4,\"name\":\"Acme Corp\",\"email\":null,\"phone\":null,\"website\":\"https:\/\/acme.test\",\"street_address\":null,\"city\":null,\"state\":null,\"postal_code\":null,\"country\":null,\"status\":{\"id\":11,\"name\":\"In Deal\",\"slug\":\"contact-in-deal\"},\"people\":[],\"custom_fields\":null,\"created_at\":\"2026-08-05T07:05:52+00:00\",\"updated_at\":\"2026-08-06T11:42:43+00:00\"}}", "name": "" }, { "header": [], "code": 404, "body": "{\"error\":{\"code\":\"not_found\",\"message\":\"Organization not found.\"}}", "name": "Organization not found" } ] }, { "name": "Delete an organization", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/organizations\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/organizations\/:id", "variable": [ { "id": "id", "key": "id", "value": 4, "description": "The organization ID." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Soft-deletes the organization, matching the internal delete behavior." }, "response": [ { "header": [], "code": 204, "body": "{}", "name": "" } ] } ] }, { "name": "Statuses", "description": "\nRead-only access to the Status definitions used by Leads, Deals, People, and\nOrganizations - lets you discover valid `status_id` values before creating\nor updating those resources. Requires a Bearer API key with the `statuses`\npermission and a Professional-plan account. Creating, reordering, and\ndeleting statuses (including reassigning or removing the records on a\nstatus) is a Settings-only capability and is not exposed via the API.", "item": [ { "name": "List statuses", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/statuses", "query": [ { "key": "type", "value": "lead", "description": "One of: lead, contact, deal, project. `contact` covers both People and Organizations.", "disabled": false }, { "key": "page", "value": "1", "description": "Page number.", "disabled": false }, { "key": "per_page", "value": "25", "description": "Results per page (default 25, max 200 - values above 200 are clamped).", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/statuses?type=lead&page=1&per_page=25" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"type\":\"lead\"}" }, "description": "Returns the statuses defined for a single type, ordered the same way\nthey appear in the Settings UI. `type=contact` covers both People and\nOrganizations - there's no separate `person`\/`organization` type." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":1,\"name\":\"New\",\"slug\":\"lead-new\",\"type\":\"lead\",\"color\":\"4299E1\",\"order\":1,\"is_locked\":true},{\"id\":2,\"name\":\"Attempted\",\"slug\":\"lead-attempted\",\"type\":\"lead\",\"color\":\"ECC94B\",\"order\":2,\"is_locked\":false},{\"id\":3,\"name\":\"Contacted\",\"slug\":\"lead-contacted\",\"type\":\"lead\",\"color\":\"ED8936\",\"order\":3,\"is_locked\":false},{\"id\":4,\"name\":\"Qualified\",\"slug\":\"lead-qualified\",\"type\":\"lead\",\"color\":\"48BB78\",\"order\":4,\"is_locked\":true},{\"id\":5,\"name\":\"Unqualified\",\"slug\":\"lead-unqualified\",\"type\":\"lead\",\"color\":\"F56565\",\"order\":5,\"is_locked\":true},{\"id\":6,\"name\":\"Converted\",\"slug\":\"lead-converted\",\"type\":\"lead\",\"color\":\"38B2AC\",\"order\":6,\"is_locked\":true},{\"id\":7,\"name\":\"Archived\",\"slug\":\"lead-archived\",\"type\":\"lead\",\"color\":\"A0AEC0\",\"order\":7,\"is_locked\":true}],\"links\":{\"first\":\"https:\/\/{your-subdomain}.saleskey.ai\/api\/v1\/statuses?type=lead&per_page=25&page=1\",\"last\":\"https:\/\/{your-subdomain}.saleskey.ai\/api\/v1\/statuses?type=lead&per_page=25&page=1\",\"prev\":null,\"next\":null},\"meta\":{\"current_page\":1,\"from\":1,\"last_page\":1,\"per_page\":25,\"to\":7,\"total\":7,\"path\":\"https:\/\/{your-subdomain}.saleskey.ai\/api\/v1\/statuses\",\"links\":[{\"url\":null,\"label\":\"\u00ab Previous\",\"page\":null,\"active\":false},{\"url\":\"https:\/\/{your-subdomain}.saleskey.ai\/api\/v1\/statuses?type=lead&per_page=25&page=1\",\"label\":\"1\",\"page\":1,\"active\":true},{\"url\":null,\"label\":\"Next \u00bb\",\"page\":null,\"active\":false}]}}", "name": "" }, { "header": [], "code": 401, "body": "{\"error\":{\"code\":\"invalid_api_key\",\"message\":\"A valid API key is required.\"}}", "name": "Missing or invalid key" }, { "header": [], "code": 403, "body": "{\"error\":{\"code\":\"plan_upgrade_required\",\"message\":\"The REST API is only available on the Professional plan. Please upgrade to continue.\"}}", "name": "Not on Professional plan" }, { "header": [], "code": 403, "body": "{\"error\":{\"code\":\"insufficient_permissions\",\"message\":\"This API key does not have 'read' permission for 'statuses'.\"}}", "name": "Key lacks permission" }, { "header": [], "code": 422, "body": "{\"error\":{\"code\":\"validation_failed\",\"message\":\"The given data was invalid.\",\"details\":{\"type\":[\"The selected type is invalid.\"]}}}", "name": "Missing or invalid type" }, { "header": [], "code": 429, "body": "{\"error\":{\"code\":\"rate_limit_exceeded\",\"message\":\"Too many requests. Please retry later.\",\"retry_after\":42}}", "name": "Rate limited" } ] }, { "name": "Retrieve a status", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/statuses\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/statuses\/:id", "variable": [ { "id": "id", "key": "id", "value": 1, "description": "The status ID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":1,\"name\":\"New\",\"slug\":\"lead-new\",\"type\":\"lead\",\"color\":\"4299E1\",\"order\":1,\"is_locked\":true}}", "name": "" }, { "header": [], "code": 404, "body": "{\"error\":{\"code\":\"not_found\",\"message\":\"Status not found.\"}}", "name": "Status not found" } ] } ] }, { "name": "Labels", "description": "\nRead-only access to the Label definitions used to tag Leads, Deals, and\nProjects. Lets you discover valid label ids to populate the `labels` field\non `POST`\/`PATCH \/leads` and `\/deals` (attaching labels to a record is\nunchanged - still handled there, not by this API). Requires a Bearer API\nkey with the `labels` permission and a Professional-plan account. Creating,\nreordering, and deleting label definitions is a Settings-only capability\nand is not exposed via the API.", "item": [ { "name": "List labels", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/labels", "query": [ { "key": "type", "value": "lead", "description": "One of: lead, deal, project.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/labels?type=lead" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"type\":\"lead\"}" }, "description": "Returns the labels defined for a single type, ordered the same way\nthey appear in the Settings UI. Not paginated - label counts per type\nare typically small." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":1,\"name\":\"Hot\",\"slug\":\"lead-hot\",\"type\":\"lead\",\"color\":\"F56565\",\"order\":1},{\"id\":2,\"name\":\"Warm\",\"slug\":\"lead-warm\",\"type\":\"lead\",\"color\":\"ED8936\",\"order\":2},{\"id\":3,\"name\":\"Cold\",\"slug\":\"lead-cold\",\"type\":\"lead\",\"color\":\"4299E1\",\"order\":3}]}", "name": "" }, { "header": [], "code": 401, "body": "{\"error\":{\"code\":\"invalid_api_key\",\"message\":\"A valid API key is required.\"}}", "name": "Missing or invalid key" }, { "header": [], "code": 403, "body": "{\"error\":{\"code\":\"plan_upgrade_required\",\"message\":\"The REST API is only available on the Professional plan. Please upgrade to continue.\"}}", "name": "Not on Professional plan" }, { "header": [], "code": 403, "body": "{\"error\":{\"code\":\"insufficient_permissions\",\"message\":\"This API key does not have 'read' permission for 'labels'.\"}}", "name": "Key lacks permission" }, { "header": [], "code": 422, "body": "{\"error\":{\"code\":\"validation_failed\",\"message\":\"The given data was invalid.\",\"details\":{\"type\":[\"The selected type is invalid.\"]}}}", "name": "Missing or invalid type" }, { "header": [], "code": 429, "body": "{\"error\":{\"code\":\"rate_limit_exceeded\",\"message\":\"Too many requests. Please retry later.\",\"retry_after\":42}}", "name": "Rate limited" } ] }, { "name": "Retrieve a label", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/labels\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/labels\/:id", "variable": [ { "id": "id", "key": "id", "value": 1, "description": "The label ID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":1,\"name\":\"Hot\",\"slug\":\"lead-hot\",\"type\":\"lead\",\"color\":\"F56565\",\"order\":1}}", "name": "" }, { "header": [], "code": 404, "body": "{\"error\":{\"code\":\"not_found\",\"message\":\"Label not found.\"}}", "name": "Label not found" } ] } ] }, { "name": "Source Channels", "description": "\nRead-only access to the Source Channel definitions used by Leads and Deals\n(e.g. Website, Referral). Lets you discover valid `source_channel_id`\nvalues before creating or updating those resources. Requires a Bearer API\nkey with the `source_channels` permission and a Professional-plan account.\nCreating, reordering, and deleting source channel definitions is a\nSettings-only capability and is not exposed via the API.", "item": [ { "name": "List source channels", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/source-channels", "query": [], "raw": "{{baseUrl}}\/api\/v1\/source-channels" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns every source channel, ordered the same way they appear in the\nSettings UI. Not paginated - source channel counts are typically small." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":1,\"name\":\"Website\",\"order\":1},{\"id\":2,\"name\":\"Referral\",\"order\":4}]}", "name": "" }, { "header": [], "code": 401, "body": "{\"error\":{\"code\":\"invalid_api_key\",\"message\":\"A valid API key is required.\"}}", "name": "Missing or invalid key" }, { "header": [], "code": 403, "body": "{\"error\":{\"code\":\"plan_upgrade_required\",\"message\":\"The REST API is only available on the Professional plan. Please upgrade to continue.\"}}", "name": "Not on Professional plan" }, { "header": [], "code": 403, "body": "{\"error\":{\"code\":\"insufficient_permissions\",\"message\":\"This API key does not have 'read' permission for 'source_channels'.\"}}", "name": "Key lacks permission" }, { "header": [], "code": 429, "body": "{\"error\":{\"code\":\"rate_limit_exceeded\",\"message\":\"Too many requests. Please retry later.\",\"retry_after\":42}}", "name": "Rate limited" } ] }, { "name": "Retrieve a source channel", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/source-channels\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/source-channels\/:id", "variable": [ { "id": "id", "key": "id", "value": 1, "description": "The source channel ID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":1,\"name\":\"Website\",\"order\":1}}", "name": "" }, { "header": [], "code": 404, "body": "{\"error\":{\"code\":\"not_found\",\"message\":\"Source channel not found.\"}}", "name": "Source channel not found" } ] } ] }, { "name": "Pipelines", "description": "\nRead-only access to Deal Pipelines and their stages. Lets you discover\nvalid `pipeline_id`\/`pipeline_stage_id` values before creating or updating\na Deal (Leads have no pipeline concept). Requires a Bearer API key with the\n`pipelines` permission and a Professional-plan account. Creating, updating,\nand deleting pipelines\/stages - including operations that can reassign or\ndelete every Deal on a pipeline - is a Settings-only capability and is not\nexposed via the API.", "item": [ { "name": "List pipelines", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/pipelines", "query": [], "raw": "{{baseUrl}}\/api\/v1\/pipelines" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns every active pipeline with its stages. Not paginated - pipeline\ncounts are typically small." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":1,\"name\":\"Deal Flow\",\"is_active\":true,\"has_probabilities\":true,\"stages\":[{\"id\":1,\"name\":\"Qualified\",\"color\":\"EF4444\",\"order\":1,\"probability\":\"10.00\"},{\"id\":2,\"name\":\"Contact Made\",\"color\":\"F59E0B\",\"order\":2,\"probability\":\"30.00\"},{\"id\":3,\"name\":\"Demo Scheduled\",\"color\":\"EAB308\",\"order\":3,\"probability\":\"50.00\"},{\"id\":4,\"name\":\"Proposal Made\",\"color\":\"3B82F6\",\"order\":4,\"probability\":\"75.00\"},{\"id\":5,\"name\":\"Negotiation Started\",\"color\":\"10B981\",\"order\":5,\"probability\":\"100.00\"}]}]}", "name": "" }, { "header": [], "code": 401, "body": "{\"error\":{\"code\":\"invalid_api_key\",\"message\":\"A valid API key is required.\"}}", "name": "Missing or invalid key" }, { "header": [], "code": 403, "body": "{\"error\":{\"code\":\"plan_upgrade_required\",\"message\":\"The REST API is only available on the Professional plan. Please upgrade to continue.\"}}", "name": "Not on Professional plan" }, { "header": [], "code": 403, "body": "{\"error\":{\"code\":\"insufficient_permissions\",\"message\":\"This API key does not have 'read' permission for 'pipelines'.\"}}", "name": "Key lacks permission" }, { "header": [], "code": 429, "body": "{\"error\":{\"code\":\"rate_limit_exceeded\",\"message\":\"Too many requests. Please retry later.\",\"retry_after\":42}}", "name": "Rate limited" } ] }, { "name": "Retrieve a pipeline", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/pipelines\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/pipelines\/:id", "variable": [ { "id": "id", "key": "id", "value": 1, "description": "The pipeline ID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":1,\"name\":\"Deal Flow\",\"is_active\":true,\"has_probabilities\":true,\"stages\":[{\"id\":1,\"name\":\"Qualified\",\"color\":\"EF4444\",\"order\":1,\"probability\":\"10.00\"},{\"id\":2,\"name\":\"Contact Made\",\"color\":\"F59E0B\",\"order\":2,\"probability\":\"30.00\"},{\"id\":3,\"name\":\"Demo Scheduled\",\"color\":\"EAB308\",\"order\":3,\"probability\":\"50.00\"},{\"id\":4,\"name\":\"Proposal Made\",\"color\":\"3B82F6\",\"order\":4,\"probability\":\"75.00\"},{\"id\":5,\"name\":\"Negotiation Started\",\"color\":\"10B981\",\"order\":5,\"probability\":\"100.00\"}]}}", "name": "" }, { "header": [], "code": 404, "body": "{\"error\":{\"code\":\"not_found\",\"message\":\"Pipeline not found.\"}}", "name": "Pipeline not found" } ] } ] }, { "name": "Users", "description": "\nRead-only access to the tenant's Users - lets you discover valid\n`owner_id`, `assignees`, and `followers` values before creating or\nupdating Leads\/Deals. Requires a Bearer API key with the `users`\npermission and a Professional-plan account. Inviting, deactivating, and\nmanaging roles for users is a Settings-only capability and is not\nexposed via the API.", "item": [ { "name": "List users", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/users", "query": [ { "key": "page", "value": "1", "description": "Page number.", "disabled": false }, { "key": "per_page", "value": "25", "description": "Results per page (default 25, max 200 - values above 200 are clamped).", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/users?page=1&per_page=25" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns a paginated list of active (non-deleted) users." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":1,\"name\":\"Jane Owner\",\"email\":\"jane@acme.test\",\"status\":\"active\",\"roles\":[\"Account Owner\"],\"created_at\":\"2026-07-23T10:00:00+00:00\",\"updated_at\":\"2026-07-23T10:00:00+00:00\"}],\"links\":{\"first\":\"...\",\"last\":\"...\",\"prev\":null,\"next\":null},\"meta\":{\"current_page\":1,\"per_page\":25,\"total\":1}}", "name": "" }, { "header": [], "code": 401, "body": "{\"error\":{\"code\":\"invalid_api_key\",\"message\":\"A valid API key is required.\"}}", "name": "Missing or invalid key" }, { "header": [], "code": 403, "body": "{\"error\":{\"code\":\"plan_upgrade_required\",\"message\":\"The REST API is only available on the Professional plan. Please upgrade to continue.\"}}", "name": "Not on Professional plan" }, { "header": [], "code": 403, "body": "{\"error\":{\"code\":\"insufficient_permissions\",\"message\":\"This API key does not have 'read' permission for 'users'.\"}}", "name": "Key lacks permission" }, { "header": [], "code": 429, "body": "{\"error\":{\"code\":\"rate_limit_exceeded\",\"message\":\"Too many requests. Please retry later.\",\"retry_after\":42}}", "name": "Rate limited" } ] }, { "name": "Retrieve a user", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/users\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/users\/:id", "variable": [ { "id": "id", "key": "id", "value": 1, "description": "The user ID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":1,\"name\":\"Jane Owner\",\"email\":\"jane@acme.test\",\"status\":\"active\",\"roles\":[\"Account Owner\"]}}", "name": "" }, { "header": [], "code": 404, "body": "{\"error\":{\"code\":\"not_found\",\"message\":\"User not found.\"}}", "name": "User not found" } ] } ] }, { "name": "Fields", "description": "\nRead-only access to the fields available on Leads, Deals, People, and\nOrganizations - both built-in and custom - including resolved options for\nselect\/multiselect fields. Lets you discover exactly what a create\/update\npayload can contain before sending one. Requires a Bearer API key with the\n`fields` permission and a Professional-plan account. Creating, editing, and\nreordering fields is a Settings-only capability and is not exposed via the\nAPI.\n\n`options` is resolved server-side wherever a real backing source exists\n(statuses, labels, source channels, users, people, organizations,\npipelines) for the built-in select fields, and read directly from the\nfield's own stored choices for custom select\/multiselect fields. Three\nbuilt-in fields can't be resolved to one flat, context-free list: a Deal's\npipeline stage (valid stages depend on which pipeline is chosen - see\n`GET \/pipelines`), and `country`\/`currency` (static lists with no backing\ntenant-DB service). For these, `options` is `null` and `options_source` is\nset to `pipeline_stages`, `countries`, or `currencies` instead.", "item": [ { "name": "List fields", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/fields", "query": [ { "key": "type", "value": "lead", "description": "One of: lead, deal, person, organization.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/fields?type=lead" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"type\":\"person\"}" }, "description": "Returns every visible built-in and custom field for a single entity\ntype, in the same order they appear in the Settings UI, including\nresolved options for select\/multiselect fields." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":29,\"slug\":\"lead_title\",\"name\":\"Title\",\"type\":\"input\",\"relation_type\":\"lead\",\"is_default\":true,\"options\":null,\"order\":1},{\"id\":32,\"slug\":\"lead_currency\",\"name\":\"Currency\",\"type\":\"select_currency\",\"relation_type\":\"lead\",\"is_default\":true,\"options\":null,\"options_source\":\"currencies\",\"order\":4},{\"id\":33,\"slug\":\"lead_value\",\"name\":\"Value\",\"type\":\"input_money\",\"relation_type\":\"lead\",\"is_default\":true,\"options\":null,\"order\":5},{\"id\":36,\"slug\":\"lead_expected_close_date\",\"name\":\"Expected Close Date\",\"type\":\"date\",\"relation_type\":\"lead\",\"is_default\":true,\"options\":null,\"order\":8},{\"id\":37,\"slug\":\"lead_person_id\",\"name\":\"Person\",\"type\":\"create_or_select_person\",\"relation_type\":\"lead\",\"is_default\":true,\"options\":[],\"order\":9},{\"id\":38,\"slug\":\"lead_organization_id\",\"name\":\"Organization\",\"type\":\"create_or_select_organization\",\"relation_type\":\"lead\",\"is_default\":true,\"options\":[],\"order\":10},{\"id\":39,\"slug\":\"lead_status_id\",\"name\":\"Status\",\"type\":\"select_status\",\"relation_type\":\"lead\",\"is_default\":true,\"options\":[{\"value\":1,\"label\":\"New\"},{\"value\":2,\"label\":\"Attempted\"},{\"value\":3,\"label\":\"Contacted\"},{\"value\":4,\"label\":\"Qualified\"},{\"value\":5,\"label\":\"Unqualified\"},{\"value\":6,\"label\":\"Converted\"},{\"value\":7,\"label\":\"Archived\"}],\"order\":11},{\"id\":40,\"slug\":\"lead_labels\",\"name\":\"Labels\",\"type\":\"multiselect_labels\",\"relation_type\":\"lead\",\"is_default\":true,\"options\":[{\"value\":1,\"label\":\"Hot\"},{\"value\":2,\"label\":\"Warm\"},{\"value\":3,\"label\":\"Cold\"}],\"order\":12},{\"id\":41,\"slug\":\"lead_source_channel_id\",\"name\":\"Source Channel\",\"type\":\"select_source_channel\",\"relation_type\":\"lead\",\"is_default\":true,\"options\":[{\"value\":1,\"label\":\"Website\"},{\"value\":2,\"label\":\"Social Media\"},{\"value\":3,\"label\":\"Email Campaign\"},{\"value\":4,\"label\":\"Referral\"},{\"value\":5,\"label\":\"Event\"},{\"value\":6,\"label\":\"Prospector\"}],\"order\":13},{\"id\":43,\"slug\":\"lead_owner_id\",\"name\":\"Owner\",\"type\":\"select_user\",\"relation_type\":\"lead\",\"is_default\":true,\"options\":[{\"value\":1,\"label\":\"Jane Owner\"}],\"order\":15},{\"id\":44,\"slug\":\"lead_assignees\",\"name\":\"Assignees\",\"type\":\"multiselect_users\",\"relation_type\":\"lead\",\"is_default\":true,\"options\":[{\"value\":1,\"label\":\"Jane Owner\"}],\"order\":16},{\"id\":542,\"slug\":\"lead_region\",\"name\":\"Region\",\"type\":\"select\",\"relation_type\":\"lead\",\"is_default\":false,\"options\":[\"Asia\",\"Europe\",\"North America\",\"South America\",\"Africa\",\"Australia\"],\"order\":21}]}", "name": "" }, { "header": [], "code": 401, "body": "{\"error\":{\"code\":\"invalid_api_key\",\"message\":\"A valid API key is required.\"}}", "name": "Missing or invalid key" }, { "header": [], "code": 403, "body": "{\"error\":{\"code\":\"plan_upgrade_required\",\"message\":\"The REST API is only available on the Professional plan. Please upgrade to continue.\"}}", "name": "Not on Professional plan" }, { "header": [], "code": 403, "body": "{\"error\":{\"code\":\"insufficient_permissions\",\"message\":\"This API key does not have 'read' permission for 'fields'.\"}}", "name": "Key lacks permission" }, { "header": [], "code": 422, "body": "{\"error\":{\"code\":\"validation_failed\",\"message\":\"The given data was invalid.\",\"details\":{\"type\":[\"The selected type is invalid.\"]}}}", "name": "Missing or invalid type" }, { "header": [], "code": 429, "body": "{\"error\":{\"code\":\"rate_limit_exceeded\",\"message\":\"Too many requests. Please retry later.\",\"retry_after\":42}}", "name": "Rate limited" } ] }, { "name": "Retrieve a field", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/fields\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/fields\/:id", "variable": [ { "id": "id", "key": "id", "value": 11, "description": "The field ID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":39,\"slug\":\"lead_status_id\",\"name\":\"Status\",\"type\":\"select_status\",\"relation_type\":\"lead\",\"is_default\":true,\"options\":[{\"value\":1,\"label\":\"New\"},{\"value\":2,\"label\":\"Attempted\"},{\"value\":3,\"label\":\"Contacted\"},{\"value\":4,\"label\":\"Qualified\"},{\"value\":5,\"label\":\"Unqualified\"},{\"value\":6,\"label\":\"Converted\"},{\"value\":7,\"label\":\"Archived\"}],\"order\":11}}", "name": "" }, { "header": [], "code": 404, "body": "{\"error\":{\"code\":\"not_found\",\"message\":\"Field not found.\"}}", "name": "Field not found" } ] } ] } ], "auth": { "type": "bearer", "bearer": [ { "key": "Authorization", "type": "string" } ] } }