{ "openapi": "3.1.0", "info": { "title": "Kanishu CRM API", "version": "v1", "description": "Generated from the product's routes (suite/api-kit). Conventions — lists, values, versions, retries, limits — are in the Kanishu API standard; every error uses the envelope below, with the codes in \"API errors\"." }, "servers": [ { "url": "https://crm.kanishu.com/api/v1" } ], "security": [ { "bearer": [] } ], "paths": { "/api-access-requests": { "post": { "operationId": "postApiAccessRequestsStore", "summary": "Create in api access requests", "tags": [ "Api" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Created. The record is in `data`; its address in `Location`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "allowed_ips": { "type": "string", "nullable": true, "maxLength": 2000 }, "api_client_id": { "type": "integer", "nullable": true }, "purpose": { "type": "string", "maxLength": 1000 }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "people:read", "people:write", "leads:read", "leads:write", "contacts:read", "contacts:write", "deals:read", "deals:write" ] }, "minItems": 1 }, "validity_days": { "type": "integer", "nullable": true, "enum": [ "30", "60", "90" ] } }, "required": [ "purpose", "scopes" ] } } } } } }, "/api-access-requests/pending": { "get": { "operationId": "getApiAccessRequestsPendingPending", "summary": "Pending (api access requests pending)", "tags": [ "Api" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "fields", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back." } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/api-access-requests/{apiAccessRequest}/approve": { "post": { "operationId": "postApiAccessRequestsApproveApprove", "summary": "Approve (api access requests approve)", "tags": [ "Api" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "apiAccessRequest", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/api-access-requests/{apiAccessRequest}/reject": { "post": { "operationId": "postApiAccessRequestsRejectReject", "summary": "Reject (api access requests reject)", "tags": [ "Api" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "apiAccessRequest", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 500 } }, "required": [ "reason" ] } } } } } }, "/api-access-requests/{apiAccessRequest}/reveal": { "get": { "operationId": "getApiAccessRequestsRevealReveal", "summary": "Reveal (api access requests reveal)", "tags": [ "Api" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "apiAccessRequest", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "fields", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back." } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "The API token, shown this once. Store it in your secrets manager and send it as Authorization: Bearer ." } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/contacts": { "get": { "operationId": "getContactsIndex", "summary": "List contacts", "tags": [ "Contacts" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Page number, from 1." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Items a page (default 25, at most 100)." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search text." }, { "name": "filter[account_id]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only records with this value; several values comma-separated mean \"any of\"." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated; prefix - for descending. Allowed: name, created_at, updated_at. Default: id." }, { "name": "fields", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back." }, { "name": "include", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Related records in the same answer, comma-separated: `account` — The company account the record belongs to (needs `contacts:read`); `owner` — The record's owner: id, name, email; `deals` — The contact's deals (only those the token's owner may see), as GET /deals returns them (needs `deals:read`); `source_lead` — The lead the record came from, as GET /leads/{lead} returns it (only if the token's owner may see it) (needs `leads:read`)." } ], "responses": { "200": { "description": "A page of results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "company": { "type": "string", "description": "Company name as typed; account_id is the linked account record." }, "account_id": { "type": "integer", "description": "The company account the contact belongs to (?include=account)." }, "owner_user_id": { "type": "integer", "description": "The salesperson who owns the contact (?include=owner)." }, "converted_from_lead_id": { "type": [ "integer", "null" ], "description": "The lead this contact was converted from, if any (?include=source_lead)." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "custom_fields": { "type": "object", "description": "Your organisation's own extra fields, by field name." }, "account": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "domain": { "type": [ "string", "null" ] }, "gstin": { "type": [ "string", "null" ] }, "owner_user_id": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "country": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "pincode": { "type": [ "string", "null" ] }, "territory_id": { "type": [ "integer", "null" ] } }, "description": "Only with ?include=account. The company account the record belongs to." }, "owner": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" } }, "description": "Only with ?include=owner. The record's owner: id, name, email." }, "deals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "contact_id": { "type": "integer" }, "source_lead_id": { "type": [ "integer", "null" ] }, "pipeline_id": { "type": "integer" }, "pipeline_stage_id": { "type": "integer" }, "value": { "type": [ "string", "null" ] }, "currency": { "type": "string" }, "fx_rate": { "type": "string" }, "fx_rate_date": { "type": "string", "format": "date-time" }, "fx_rate_source": { "type": "string" }, "value_home": { "type": "string" }, "forecast_category": { "type": [ "string", "null" ] }, "expected_close_date": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string" }, "stale_alert_sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "owner_user_id": { "type": "integer" }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" }, "close_reason": { "type": [ "string", "null" ] }, "close_note": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "custom_fields": { "type": "object" } } }, "description": "Only with ?include=deals. The contact's deals (only those the token's owner may see), as GET /deals returns them." }, "source_lead": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "company": { "type": "string" }, "account_id": { "type": "integer" }, "source": { "type": "string" }, "status": { "type": "string" }, "disqualified_reason": { "type": [ "string", "null" ] }, "score": { "type": "integer" }, "stale_alert_sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "owner_user_id": { "type": "integer" }, "converted_to_contact_id": { "type": "integer" }, "converted_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "country": { "type": "string" }, "state": { "type": "string" }, "city": { "type": "string" }, "pincode": { "type": "string" }, "territory_id": { "type": [ "integer", "null" ] }, "custom_fields": { "type": "object" } }, "description": "Only with ?include=source_lead. The lead the record came from, as GET /leads/{lead} returns it (only if the token's owner may see it)." } } }, "type": "array" }, "meta": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "last_page": { "type": "integer" }, "current_page": { "type": "integer" } } }, "links": { "type": "object", "properties": { "first": { "type": "string" }, "prev": { "type": [ "string", "null" ], "format": "uri" }, "next": { "type": [ "string", "null" ], "format": "uri" }, "last": { "type": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `contacts:read` scope.", "x-scope": "contacts:read" }, "post": { "operationId": "postContactsStore", "summary": "Create in contacts", "tags": [ "Contacts" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Created. The record is in `data`; its address in `Location`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "company": { "type": "string", "description": "Company name as typed; account_id is the linked account record." }, "account_id": { "type": "integer", "description": "The company account the contact belongs to (?include=account)." }, "owner_user_id": { "type": "integer", "description": "The salesperson who owns the contact (?include=owner)." }, "converted_from_lead_id": { "type": [ "integer", "null" ], "description": "The lead this contact was converted from, if any (?include=source_lead)." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "custom_fields": { "type": "object", "description": "Your organisation's own extra fields, by field name." } } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `contacts:write` scope.", "x-scope": "contacts:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "company": { "type": "string", "nullable": true, "maxLength": 255, "description": "Company name as typed; account_id is the linked account record." }, "email": { "type": "string", "nullable": true, "format": "email", "maxLength": 255 }, "name": { "type": "string", "maxLength": 255 }, "phone": { "type": "string", "nullable": true, "maxLength": 50 } }, "required": [ "name" ] } } } } } }, "/contacts/{contact}": { "get": { "operationId": "getContactsShow", "summary": "Get one of contacts", "tags": [ "Contacts" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "contact", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "fields", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back." }, { "name": "include", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Related records in the same answer, comma-separated: `account` — The company account the record belongs to (needs `contacts:read`); `owner` — The record's owner: id, name, email; `deals` — The contact's deals (only those the token's owner may see), as GET /deals returns them (needs `deals:read`); `source_lead` — The lead the record came from, as GET /leads/{lead} returns it (only if the token's owner may see it) (needs `leads:read`)." } ], "responses": { "200": { "description": "OK. The record is in `data`, with its version in the `ETag` header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "company": { "type": "string", "description": "Company name as typed; account_id is the linked account record." }, "account_id": { "type": "integer", "description": "The company account the contact belongs to (?include=account)." }, "owner_user_id": { "type": "integer", "description": "The salesperson who owns the contact (?include=owner)." }, "converted_from_lead_id": { "type": [ "integer", "null" ], "description": "The lead this contact was converted from, if any (?include=source_lead)." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "custom_fields": { "type": "object", "description": "Your organisation's own extra fields, by field name." }, "account": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "domain": { "type": "string" }, "gstin": { "type": "string" }, "owner_user_id": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "country": { "type": "string" }, "state": { "type": "string" }, "city": { "type": "string" }, "pincode": { "type": "string" }, "territory_id": { "type": [ "integer", "null" ] } }, "description": "Only with ?include=account. The company account the record belongs to." }, "owner": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" } }, "description": "Only with ?include=owner. The record's owner: id, name, email." }, "deals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "contact_id": { "type": "integer" }, "source_lead_id": { "type": [ "integer", "null" ] }, "pipeline_id": { "type": "integer" }, "pipeline_stage_id": { "type": "integer" }, "value": { "type": "string" }, "currency": { "type": "string" }, "fx_rate": { "type": "string" }, "fx_rate_date": { "type": "string", "format": "date-time" }, "fx_rate_source": { "type": "string" }, "value_home": { "type": "string" }, "forecast_category": { "type": "string" }, "expected_close_date": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "stale_alert_sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "owner_user_id": { "type": "integer" }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" }, "close_reason": { "type": [ "string", "null" ] }, "close_note": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "custom_fields": { "type": "object" } } }, "description": "Only with ?include=deals. The contact's deals (only those the token's owner may see), as GET /deals returns them." }, "source_lead": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "company": { "type": "string" }, "account_id": { "type": "integer" }, "source": { "type": "string" }, "status": { "type": "string" }, "disqualified_reason": { "type": [ "string", "null" ] }, "score": { "type": "integer" }, "stale_alert_sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "owner_user_id": { "type": "integer" }, "converted_to_contact_id": { "type": "integer" }, "converted_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "country": { "type": "string" }, "state": { "type": "string" }, "city": { "type": "string" }, "pincode": { "type": "string" }, "territory_id": { "type": [ "integer", "null" ] }, "custom_fields": { "type": "object" } }, "description": "Only with ?include=source_lead. The lead the record came from, as GET /leads/{lead} returns it (only if the token's owner may see it)." } } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `contacts:read` scope.", "x-scope": "contacts:read" }, "patch": { "operationId": "patchContactsUpdate", "summary": "Change one of contacts", "tags": [ "Contacts" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "contact", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "OK. The record is in `data`, with its version in the `ETag` header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "company": { "type": "string", "description": "Company name as typed; account_id is the linked account record." }, "account_id": { "type": "integer", "description": "The company account the contact belongs to (?include=account)." }, "owner_user_id": { "type": "integer", "description": "The salesperson who owns the contact (?include=owner)." }, "converted_from_lead_id": { "type": [ "integer", "null" ], "description": "The lead this contact was converted from, if any (?include=source_lead)." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "custom_fields": { "type": "object", "description": "Your organisation's own extra fields, by field name." } } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "412": { "$ref": "#/components/responses/E412" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `contacts:write` scope.", "x-scope": "contacts:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "company": { "type": "string", "nullable": true, "maxLength": 255, "description": "Company name as typed; account_id is the linked account record." }, "email": { "type": "string", "nullable": true, "format": "email", "maxLength": 255 }, "name": { "type": "string", "maxLength": 255 }, "phone": { "type": "string", "nullable": true, "maxLength": 50 } } } } } } } }, "/deals": { "get": { "operationId": "getDealsIndex", "summary": "List deals", "tags": [ "Deals" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Page number, from 1." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Items a page (default 25, at most 100)." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search text." }, { "name": "filter[status]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only records with this value; several values comma-separated mean \"any of\"." }, { "name": "filter[pipeline_stage_id]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only records with this value; several values comma-separated mean \"any of\"." }, { "name": "filter[contact_id]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only records with this value; several values comma-separated mean \"any of\"." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated; prefix - for descending. Allowed: title, value, expected_close_date, created_at, updated_at. Default: id." }, { "name": "fields", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back." }, { "name": "include", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Related records in the same answer, comma-separated: `contact` — The deal's contact, as GET /contacts/{contact} returns it (needs `contacts:read`); `stage` — The deal's pipeline stage: id, name, probability_percent, is_won_stage, is_lost_stage, and its pipeline (id, name); `owner` — The record's owner: id, name, email; `source_lead` — The lead the record came from, as GET /leads/{lead} returns it (only if the token's owner may see it) (needs `leads:read`)." } ], "responses": { "200": { "description": "A page of results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "contact_id": { "type": "integer", "description": "The deal's contact (?include=contact)." }, "source_lead_id": { "type": [ "integer", "null" ], "description": "The lead the deal came from, if any (?include=source_lead)." }, "pipeline_id": { "type": "integer", "description": "The sales pipeline the deal is in." }, "pipeline_stage_id": { "type": "integer", "description": "The stage within that pipeline (?include=stage returns its name and win probability)." }, "value": { "type": [ "string", "null" ], "description": "Deal value in the deal's own currency." }, "currency": { "type": "string", "description": "ISO currency code of value (e.g. INR, USD)." }, "fx_rate": { "type": "string", "description": "Exchange rate used for value_home (1 unit of currency in home currency)." }, "fx_rate_date": { "type": "string", "format": "date-time", "description": "The date of that exchange rate." }, "fx_rate_source": { "type": "string", "description": "Where the rate came from (e.g. the reference rate service, or typed in)." }, "value_home": { "type": "string", "description": "The value in your organisation's home currency, at the exchange rate fixed when entered." }, "forecast_category": { "type": [ "string", "null" ], "description": "commit, best_case, pipeline or omitted — how sure the owner is it will close." }, "expected_close_date": { "type": [ "string", "null" ], "format": "date-time", "description": "When the deal is expected to close." }, "status": { "type": "string", "description": "open, won or lost." }, "stale_alert_sent_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the owner was last reminded that the deal had no activity." }, "owner_user_id": { "type": "integer", "description": "The salesperson who owns the deal (?include=owner)." }, "closed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was marked won or lost." }, "close_reason": { "type": [ "string", "null" ], "description": "Why it was won or lost: Price, Timing, Competitor, No budget, No response, Feature gap or Other." }, "close_note": { "type": [ "string", "null" ], "description": "Free-text note recorded when it was closed." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "custom_fields": { "type": "object", "description": "Your organisation's own extra fields, by field name." }, "contact": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "company": { "type": "string" }, "account_id": { "type": "integer" }, "owner_user_id": { "type": "integer" }, "converted_from_lead_id": { "type": [ "integer", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "custom_fields": { "type": "object" } }, "description": "Only with ?include=contact. The deal's contact, as GET /contacts/{contact} returns it." }, "stage": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "probability_percent": { "type": "integer", "description": "The chance of winning at this stage, used for weighted forecasts." }, "is_won_stage": { "type": "boolean", "description": "true if reaching this stage means the deal is won." }, "is_lost_stage": { "type": "boolean", "description": "true if reaching this stage means the deal is lost." }, "pipeline": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "description": "Only with ?include=stage. The deal's pipeline stage: id, name, probability_percent, is_won_stage, is_lost_stage, and its pipeline (id, name)." }, "owner": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" } }, "description": "Only with ?include=owner. The record's owner: id, name, email." }, "source_lead": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "company": { "type": "string" }, "account_id": { "type": "integer" }, "source": { "type": "string" }, "status": { "type": "string" }, "disqualified_reason": { "type": [ "string", "null" ] }, "score": { "type": "integer" }, "stale_alert_sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "owner_user_id": { "type": "integer" }, "converted_to_contact_id": { "type": "integer" }, "converted_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "country": { "type": "string" }, "state": { "type": "string" }, "city": { "type": "string" }, "pincode": { "type": "string" }, "territory_id": { "type": [ "integer", "null" ] }, "custom_fields": { "type": "object" } }, "description": "Only with ?include=source_lead. The lead the record came from, as GET /leads/{lead} returns it (only if the token's owner may see it)." } } }, "type": "array" }, "meta": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "last_page": { "type": "integer" }, "current_page": { "type": "integer" } } }, "links": { "type": "object", "properties": { "first": { "type": "string" }, "prev": { "type": [ "string", "null" ], "format": "uri" }, "next": { "type": [ "string", "null" ], "format": "uri" }, "last": { "type": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `deals:read` scope.", "x-scope": "deals:read" }, "post": { "operationId": "postDealsStore", "summary": "Create in deals", "tags": [ "Deals" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Created. The record is in `data`; its address in `Location`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "contact_id": { "type": "integer", "description": "The deal's contact (?include=contact)." }, "source_lead_id": { "type": "integer", "description": "The lead the deal came from, if any (?include=source_lead)." }, "pipeline_id": { "type": "integer", "description": "The sales pipeline the deal is in." }, "pipeline_stage_id": { "type": "integer", "description": "The stage within that pipeline (?include=stage returns its name and win probability)." }, "value": { "type": [ "string", "null" ], "description": "Deal value in the deal's own currency." }, "currency": { "type": "string", "description": "ISO currency code of value (e.g. INR, USD)." }, "fx_rate": { "type": "string", "description": "Exchange rate used for value_home (1 unit of currency in home currency)." }, "fx_rate_date": { "type": "string", "format": "date-time", "description": "The date of that exchange rate." }, "fx_rate_source": { "type": "string", "description": "Where the rate came from (e.g. the reference rate service, or typed in)." }, "value_home": { "type": "string", "description": "The value in your organisation's home currency, at the exchange rate fixed when entered." }, "forecast_category": { "type": [ "string", "null" ], "description": "commit, best_case, pipeline or omitted — how sure the owner is it will close." }, "expected_close_date": { "type": [ "string", "null" ], "format": "date-time", "description": "When the deal is expected to close." }, "status": { "type": "string", "description": "open, won or lost." }, "stale_alert_sent_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the owner was last reminded that the deal had no activity." }, "owner_user_id": { "type": "integer", "description": "The salesperson who owns the deal (?include=owner)." }, "closed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was marked won or lost." }, "close_reason": { "type": [ "string", "null" ], "description": "Why it was won or lost: Price, Timing, Competitor, No budget, No response, Feature gap or Other." }, "close_note": { "type": [ "string", "null" ], "description": "Free-text note recorded when it was closed." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "custom_fields": { "type": "object", "description": "Your organisation's own extra fields, by field name." } } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `deals:write` scope.", "x-scope": "deals:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": "string", "nullable": true, "description": "The deal's contact (?include=contact)." }, "currency": { "type": "string", "nullable": true, "description": "ISO currency code of value (e.g. INR, USD)." }, "expected_close_date": { "type": "string", "nullable": true, "format": "date", "description": "When the deal is expected to close." }, "pipeline_id": { "type": "string", "description": "The sales pipeline the deal is in." }, "pipeline_stage_id": { "type": "string", "description": "The stage within that pipeline (?include=stage returns its name and win probability)." }, "title": { "type": "string", "maxLength": 255 }, "value": { "type": "number", "nullable": true, "minimum": 0, "description": "Deal value in the deal's own currency." } }, "required": [ "pipeline_id", "pipeline_stage_id", "title" ] } } } } } }, "/deals/{deal}": { "get": { "operationId": "getDealsShow", "summary": "Get one of deals", "tags": [ "Deals" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "deal", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "fields", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back." }, { "name": "include", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Related records in the same answer, comma-separated: `contact` — The deal's contact, as GET /contacts/{contact} returns it (needs `contacts:read`); `stage` — The deal's pipeline stage: id, name, probability_percent, is_won_stage, is_lost_stage, and its pipeline (id, name); `owner` — The record's owner: id, name, email; `source_lead` — The lead the record came from, as GET /leads/{lead} returns it (only if the token's owner may see it) (needs `leads:read`)." } ], "responses": { "200": { "description": "OK. The record is in `data`, with its version in the `ETag` header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "contact_id": { "type": "integer", "description": "The deal's contact (?include=contact)." }, "source_lead_id": { "type": "integer", "description": "The lead the deal came from, if any (?include=source_lead)." }, "pipeline_id": { "type": "integer", "description": "The sales pipeline the deal is in." }, "pipeline_stage_id": { "type": "integer", "description": "The stage within that pipeline (?include=stage returns its name and win probability)." }, "value": { "type": [ "string", "null" ], "description": "Deal value in the deal's own currency." }, "currency": { "type": "string", "description": "ISO currency code of value (e.g. INR, USD)." }, "fx_rate": { "type": "string", "description": "Exchange rate used for value_home (1 unit of currency in home currency)." }, "fx_rate_date": { "type": "string", "format": "date-time", "description": "The date of that exchange rate." }, "fx_rate_source": { "type": "string", "description": "Where the rate came from (e.g. the reference rate service, or typed in)." }, "value_home": { "type": "string", "description": "The value in your organisation's home currency, at the exchange rate fixed when entered." }, "forecast_category": { "type": [ "string", "null" ], "description": "commit, best_case, pipeline or omitted — how sure the owner is it will close." }, "expected_close_date": { "type": [ "string", "null" ], "format": "date-time", "description": "When the deal is expected to close." }, "status": { "type": "string", "description": "open, won or lost." }, "stale_alert_sent_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the owner was last reminded that the deal had no activity." }, "owner_user_id": { "type": "integer", "description": "The salesperson who owns the deal (?include=owner)." }, "closed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was marked won or lost." }, "close_reason": { "type": [ "string", "null" ], "description": "Why it was won or lost: Price, Timing, Competitor, No budget, No response, Feature gap or Other." }, "close_note": { "type": [ "string", "null" ], "description": "Free-text note recorded when it was closed." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "custom_fields": { "type": "object", "description": "Your organisation's own extra fields, by field name." }, "contact": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "company": { "type": "string" }, "account_id": { "type": "integer" }, "owner_user_id": { "type": "integer" }, "converted_from_lead_id": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "custom_fields": { "type": "object" } }, "description": "Only with ?include=contact. The deal's contact, as GET /contacts/{contact} returns it." }, "stage": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "probability_percent": { "type": "integer", "description": "The chance of winning at this stage, used for weighted forecasts." }, "is_won_stage": { "type": "boolean", "description": "true if reaching this stage means the deal is won." }, "is_lost_stage": { "type": "boolean", "description": "true if reaching this stage means the deal is lost." }, "pipeline": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "description": "Only with ?include=stage. The deal's pipeline stage: id, name, probability_percent, is_won_stage, is_lost_stage, and its pipeline (id, name)." }, "owner": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" } }, "description": "Only with ?include=owner. The record's owner: id, name, email." }, "source_lead": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "company": { "type": "string" }, "account_id": { "type": "integer" }, "source": { "type": "string" }, "status": { "type": "string" }, "disqualified_reason": { "type": [ "string", "null" ] }, "score": { "type": "integer" }, "stale_alert_sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "owner_user_id": { "type": "integer" }, "converted_to_contact_id": { "type": "integer" }, "converted_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "country": { "type": "string" }, "state": { "type": "string" }, "city": { "type": "string" }, "pincode": { "type": "string" }, "territory_id": { "type": [ "integer", "null" ] }, "custom_fields": { "type": "object" } }, "description": "Only with ?include=source_lead. The lead the record came from, as GET /leads/{lead} returns it (only if the token's owner may see it)." } } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `deals:read` scope.", "x-scope": "deals:read" }, "patch": { "operationId": "patchDealsUpdate", "summary": "Change one of deals", "tags": [ "Deals" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "deal", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "OK. The record is in `data`, with its version in the `ETag` header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "contact_id": { "type": "integer", "description": "The deal's contact (?include=contact)." }, "source_lead_id": { "type": "integer", "description": "The lead the deal came from, if any (?include=source_lead)." }, "pipeline_id": { "type": "integer", "description": "The sales pipeline the deal is in." }, "pipeline_stage_id": { "type": "integer", "description": "The stage within that pipeline (?include=stage returns its name and win probability)." }, "value": { "type": [ "string", "null" ], "description": "Deal value in the deal's own currency." }, "currency": { "type": "string", "description": "ISO currency code of value (e.g. INR, USD)." }, "fx_rate": { "type": "string", "description": "Exchange rate used for value_home (1 unit of currency in home currency)." }, "fx_rate_date": { "type": "string", "format": "date-time", "description": "The date of that exchange rate." }, "fx_rate_source": { "type": "string", "description": "Where the rate came from (e.g. the reference rate service, or typed in)." }, "value_home": { "type": "string", "description": "The value in your organisation's home currency, at the exchange rate fixed when entered." }, "forecast_category": { "type": [ "string", "null" ], "description": "commit, best_case, pipeline or omitted — how sure the owner is it will close." }, "expected_close_date": { "type": [ "string", "null" ], "format": "date-time", "description": "When the deal is expected to close." }, "status": { "type": "string", "description": "open, won or lost." }, "stale_alert_sent_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the owner was last reminded that the deal had no activity." }, "owner_user_id": { "type": "integer", "description": "The salesperson who owns the deal (?include=owner)." }, "closed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was marked won or lost." }, "close_reason": { "type": [ "string", "null" ], "description": "Why it was won or lost: Price, Timing, Competitor, No budget, No response, Feature gap or Other." }, "close_note": { "type": [ "string", "null" ], "description": "Free-text note recorded when it was closed." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "custom_fields": { "type": "object", "description": "Your organisation's own extra fields, by field name." } } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "412": { "$ref": "#/components/responses/E412" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `deals:write` scope.", "x-scope": "deals:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expected_close_date": { "type": "string", "nullable": true, "format": "date", "description": "When the deal is expected to close." }, "title": { "type": "string", "maxLength": 255 }, "value": { "type": "number", "nullable": true, "minimum": 0, "description": "Deal value in the deal's own currency." } } } } } } } }, "/leads": { "get": { "operationId": "getLeadsIndex", "summary": "List leads", "tags": [ "Leads" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Page number, from 1." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Items a page (default 25, at most 100)." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search text." }, { "name": "filter[status]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only records with this value; several values comma-separated mean \"any of\"." }, { "name": "filter[source]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only records with this value; several values comma-separated mean \"any of\"." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated; prefix - for descending. Allowed: name, score, created_at, updated_at. Default: id." }, { "name": "fields", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back." }, { "name": "include", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Related records in the same answer, comma-separated: `account` — The company account the record belongs to (needs `contacts:read`); `owner` — The record's owner: id, name, email; `converted_contact` — The contact the lead was converted to, as GET /contacts/{contact} returns it (needs `contacts:read`)." } ], "responses": { "200": { "description": "A page of results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "company": { "type": "string" }, "account_id": { "type": [ "integer", "null" ], "description": "The company account the lead belongs to, if linked (?include=account returns it)." }, "source": { "type": "string", "description": "Where the lead came from (e.g. website, referral, event) — your own wording." }, "status": { "type": "string", "description": "new, contacted, qualified, unqualified or converted." }, "disqualified_reason": { "type": [ "string", "null" ], "description": "Why the lead was marked unqualified, if it was." }, "score": { "type": "integer", "description": "Lead score from your scoring rules (higher is warmer)." }, "stale_alert_sent_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the owner was last reminded that the lead had no activity." }, "owner_user_id": { "type": "integer", "description": "The salesperson who owns the lead (?include=owner returns id, name, email)." }, "converted_to_contact_id": { "type": [ "integer", "null" ], "description": "The contact the lead became when converted (?include=converted_contact)." }, "converted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the lead was converted." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "country": { "type": "string" }, "state": { "type": "string" }, "city": { "type": "string" }, "pincode": { "type": "string", "description": "Postal code (PIN code in India)." }, "territory_id": { "type": [ "integer", "null" ], "description": "The sales territory, set from the location by your territory rules." }, "custom_fields": { "type": "object", "description": "Your organisation's own extra fields, by field name." }, "account": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "domain": { "type": [ "string", "null" ] }, "gstin": { "type": [ "string", "null" ] }, "owner_user_id": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "country": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "pincode": { "type": [ "string", "null" ] }, "territory_id": { "type": [ "integer", "null" ] } }, "description": "Only with ?include=account. The company account the record belongs to." }, "owner": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" } }, "description": "Only with ?include=owner. The record's owner: id, name, email." }, "converted_contact": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "company": { "type": "string" }, "account_id": { "type": "integer" }, "owner_user_id": { "type": "integer" }, "converted_from_lead_id": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "custom_fields": { "type": "object" } }, "description": "Only with ?include=converted_contact. The contact the lead was converted to, as GET /contacts/{contact} returns it." } } }, "type": "array" }, "meta": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "last_page": { "type": "integer" }, "current_page": { "type": "integer" } } }, "links": { "type": "object", "properties": { "first": { "type": "string" }, "prev": { "type": [ "string", "null" ], "format": "uri" }, "next": { "type": [ "string", "null" ], "format": "uri" }, "last": { "type": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `leads:read` scope.", "x-scope": "leads:read" }, "post": { "operationId": "postLeadsStore", "summary": "Create in leads", "tags": [ "Leads" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Created. The record is in `data`; its address in `Location`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "company": { "type": "string" }, "account_id": { "type": [ "integer", "null" ], "description": "The company account the lead belongs to, if linked (?include=account returns it)." }, "source": { "type": "string", "description": "Where the lead came from (e.g. website, referral, event) — your own wording." }, "status": { "type": "string", "description": "new, contacted, qualified, unqualified or converted." }, "disqualified_reason": { "type": [ "string", "null" ], "description": "Why the lead was marked unqualified, if it was." }, "score": { "type": "integer", "description": "Lead score from your scoring rules (higher is warmer)." }, "stale_alert_sent_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the owner was last reminded that the lead had no activity." }, "owner_user_id": { "type": "integer", "description": "The salesperson who owns the lead (?include=owner returns id, name, email)." }, "converted_to_contact_id": { "type": [ "integer", "null" ], "description": "The contact the lead became when converted (?include=converted_contact)." }, "converted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the lead was converted." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "country": { "type": "string" }, "state": { "type": "string" }, "city": { "type": "string" }, "pincode": { "type": "string", "description": "Postal code (PIN code in India)." }, "territory_id": { "type": [ "integer", "null" ], "description": "The sales territory, set from the location by your territory rules." }, "custom_fields": { "type": "object", "description": "Your organisation's own extra fields, by field name." } } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `leads:write` scope.", "x-scope": "leads:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "city": { "type": "string", "nullable": true, "maxLength": 80 }, "company": { "type": "string", "nullable": true, "maxLength": 255 }, "country": { "type": "string", "nullable": true, "maxLength": 80 }, "email": { "type": "string", "nullable": true, "format": "email", "maxLength": 255 }, "name": { "type": "string", "maxLength": 255 }, "phone": { "type": "string", "nullable": true, "maxLength": 50 }, "pincode": { "type": "string", "nullable": true, "maxLength": 12, "description": "Postal code (PIN code in India)." }, "source": { "type": "string", "nullable": true, "maxLength": 255, "description": "Where the lead came from (e.g. website, referral, event) — your own wording." }, "state": { "type": "string", "nullable": true, "maxLength": 80 } }, "required": [ "name" ] } } } } } }, "/leads/{lead}": { "get": { "operationId": "getLeadsShow", "summary": "Get one of leads", "tags": [ "Leads" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "lead", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "fields", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back." }, { "name": "include", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Related records in the same answer, comma-separated: `account` — The company account the record belongs to (needs `contacts:read`); `owner` — The record's owner: id, name, email; `converted_contact` — The contact the lead was converted to, as GET /contacts/{contact} returns it (needs `contacts:read`)." } ], "responses": { "200": { "description": "OK. The record is in `data`, with its version in the `ETag` header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "company": { "type": "string" }, "account_id": { "type": [ "integer", "null" ], "description": "The company account the lead belongs to, if linked (?include=account returns it)." }, "source": { "type": "string", "description": "Where the lead came from (e.g. website, referral, event) — your own wording." }, "status": { "type": "string", "description": "new, contacted, qualified, unqualified or converted." }, "disqualified_reason": { "type": [ "string", "null" ], "description": "Why the lead was marked unqualified, if it was." }, "score": { "type": "integer", "description": "Lead score from your scoring rules (higher is warmer)." }, "stale_alert_sent_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the owner was last reminded that the lead had no activity." }, "owner_user_id": { "type": "integer", "description": "The salesperson who owns the lead (?include=owner returns id, name, email)." }, "converted_to_contact_id": { "type": [ "integer", "null" ], "description": "The contact the lead became when converted (?include=converted_contact)." }, "converted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the lead was converted." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "country": { "type": "string" }, "state": { "type": "string" }, "city": { "type": "string" }, "pincode": { "type": "string", "description": "Postal code (PIN code in India)." }, "territory_id": { "type": [ "integer", "null" ], "description": "The sales territory, set from the location by your territory rules." }, "custom_fields": { "type": "object", "description": "Your organisation's own extra fields, by field name." }, "account": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "domain": { "type": [ "string", "null" ] }, "gstin": { "type": [ "string", "null" ] }, "owner_user_id": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "country": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "pincode": { "type": [ "string", "null" ] }, "territory_id": { "type": [ "integer", "null" ] } }, "description": "Only with ?include=account. The company account the record belongs to." }, "owner": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" } }, "description": "Only with ?include=owner. The record's owner: id, name, email." }, "converted_contact": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "company": { "type": "string" }, "account_id": { "type": "integer" }, "owner_user_id": { "type": "integer" }, "converted_from_lead_id": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "custom_fields": { "type": "object" } }, "description": "Only with ?include=converted_contact. The contact the lead was converted to, as GET /contacts/{contact} returns it." } } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `leads:read` scope.", "x-scope": "leads:read" }, "patch": { "operationId": "patchLeadsUpdate", "summary": "Change one of leads", "tags": [ "Leads" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "lead", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "OK. The record is in `data`, with its version in the `ETag` header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "company": { "type": "string" }, "account_id": { "type": [ "integer", "null" ], "description": "The company account the lead belongs to, if linked (?include=account returns it)." }, "source": { "type": "string", "description": "Where the lead came from (e.g. website, referral, event) — your own wording." }, "status": { "type": "string", "description": "new, contacted, qualified, unqualified or converted." }, "disqualified_reason": { "type": [ "string", "null" ], "description": "Why the lead was marked unqualified, if it was." }, "score": { "type": "integer", "description": "Lead score from your scoring rules (higher is warmer)." }, "stale_alert_sent_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the owner was last reminded that the lead had no activity." }, "owner_user_id": { "type": "integer", "description": "The salesperson who owns the lead (?include=owner returns id, name, email)." }, "converted_to_contact_id": { "type": [ "integer", "null" ], "description": "The contact the lead became when converted (?include=converted_contact)." }, "converted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the lead was converted." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "country": { "type": "string" }, "state": { "type": "string" }, "city": { "type": "string" }, "pincode": { "type": "string", "description": "Postal code (PIN code in India)." }, "territory_id": { "type": [ "integer", "null" ], "description": "The sales territory, set from the location by your territory rules." }, "custom_fields": { "type": "object", "description": "Your organisation's own extra fields, by field name." } } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "412": { "$ref": "#/components/responses/E412" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `leads:write` scope.", "x-scope": "leads:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "city": { "type": "string", "nullable": true, "maxLength": 80 }, "company": { "type": "string", "nullable": true, "maxLength": 255 }, "country": { "type": "string", "nullable": true, "maxLength": 80 }, "email": { "type": "string", "nullable": true, "format": "email", "maxLength": 255 }, "name": { "type": "string", "maxLength": 255 }, "phone": { "type": "string", "nullable": true, "maxLength": 50 }, "pincode": { "type": "string", "nullable": true, "maxLength": 12, "description": "Postal code (PIN code in India)." }, "state": { "type": "string", "nullable": true, "maxLength": 80 }, "status": { "type": "string", "enum": [ "new", "contacted", "qualified", "unqualified", "converted" ], "description": "new, contacted, qualified, unqualified or converted." } } } } } } } }, "/people": { "get": { "operationId": "getPeopleIndex", "summary": "List people", "tags": [ "People" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Page number, from 1." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Items a page (default 25, at most 100)." }, { "name": "fields", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back." } ], "responses": { "200": { "description": "A page of results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The person's id in People (a UUID). Use it with /people/{person}." }, "display_name": { "type": "string", "description": "The name shown everywhere in Kanishu." }, "preferred_name": { "type": [ "string", "null" ], "description": "What they like to be called, if different." }, "work_email": { "type": "string", "description": "Their work email address; how they are matched to logins in the products." }, "employee_number": { "type": [ "string", "null" ], "description": "Your own employee number for them (e.g. from payroll or HR)." }, "type": { "type": "string", "description": "employee, contractor, external (auditor, consultant…) or other." }, "status": { "type": "string", "description": "pre_joining (joining soon), active, on_leave, leaving (last working day set) or left." }, "joining_date": { "type": [ "string", "null" ], "format": "date", "description": "Their first working day." }, "last_working_date": { "type": [ "string", "null" ], "format": "date", "description": "Their last working day, once they are leaving; their logins are switched off after it." }, "access_end_date": { "type": [ "string", "null" ], "format": "date", "description": "When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors)." }, "department": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their department or team (id and name), from GET /people-organisation." }, "position": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their job position (id and name)." }, "location": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their office or site (id and name)." }, "manager": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string" } }, "description": "Their manager in People (id and display_name)." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "type": "array" }, "meta": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "last_page": { "type": "integer" }, "current_page": { "type": "integer" } } }, "links": { "type": "object", "properties": { "first": { "type": "string" }, "prev": { "type": [ "string", "null" ], "format": "uri" }, "next": { "type": [ "string", "null" ], "format": "uri" }, "last": { "type": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `people:read` scope.", "x-scope": "people:read" }, "post": { "operationId": "postPeopleStore", "summary": "Create in people", "tags": [ "People" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Created. The record is in `data`; its address in `Location`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The person's id in People (a UUID). Use it with /people/{person}." }, "display_name": { "type": "string", "description": "The name shown everywhere in Kanishu." }, "preferred_name": { "type": [ "string", "null" ], "description": "What they like to be called, if different." }, "work_email": { "type": "string", "description": "Their work email address; how they are matched to logins in the products." }, "employee_number": { "type": [ "string", "null" ], "description": "Your own employee number for them (e.g. from payroll or HR)." }, "type": { "type": "string", "description": "employee, contractor, external (auditor, consultant…) or other." }, "status": { "type": "string", "description": "pre_joining (joining soon), active, on_leave, leaving (last working day set) or left." }, "joining_date": { "type": "string", "format": "date", "description": "Their first working day." }, "last_working_date": { "type": [ "string", "null" ], "format": "date", "description": "Their last working day, once they are leaving; their logins are switched off after it." }, "access_end_date": { "type": [ "string", "null" ], "format": "date", "description": "When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors)." }, "department": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their department or team (id and name), from GET /people-organisation." }, "position": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their job position (id and name)." }, "location": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their office or site (id and name)." }, "manager": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string" } }, "description": "Their manager in People (id and display_name)." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `people:write` scope.", "x-scope": "people:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "access_end_date": { "type": "string", "nullable": true, "format": "date", "description": "When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors)." }, "display_name": { "type": "string", "maxLength": 255, "description": "The name shown everywhere in Kanishu." }, "employee_number": { "type": "string", "nullable": true, "maxLength": 50, "description": "Your own employee number for them (e.g. from payroll or HR)." }, "employment_status": { "type": "string", "enum": [ "pre_joining", "active", "on_leave", "leaving", "left" ], "description": "pre_joining (joining soon), active, on_leave, leaving (last working day set) or left." }, "joining_date": { "type": "string", "nullable": true, "format": "date", "description": "Their first working day." }, "location_id": { "type": "string", "nullable": true, "format": "uuid" }, "manager_person_id": { "type": "string", "nullable": true, "format": "uuid", "description": "The manager's People id." }, "org_unit_id": { "type": "string", "nullable": true, "format": "uuid", "description": "The department or team id, from GET /people-organisation." }, "person_type": { "type": "string", "enum": [ "employee", "contractor", "external", "other" ], "description": "employee, contractor, external (auditor, consultant…) or other." }, "position_id": { "type": "string", "nullable": true, "format": "uuid" }, "preferred_name": { "type": "string", "nullable": true, "maxLength": 255, "description": "What they like to be called, if different." }, "work_email": { "type": "string", "nullable": true, "format": "email", "maxLength": 255, "description": "Their work email address; how they are matched to logins in the products." } }, "required": [ "display_name" ] } } } } } }, "/people-organisation": { "get": { "operationId": "getPeopleOrganisationOrganisation", "summary": "Organisation (people organisation)", "tags": [ "People" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "fields", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back." } ], "responses": { "200": { "description": "OK. The record is in `data`, with its version in the `ETag` header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "departments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "type": { "type": "string", "description": "What kind of unit it is (e.g. department, team, business unit)." }, "code": { "type": "string" }, "part_of_id": { "type": [ "integer", "string", "null" ], "description": "The unit this one sits under, or null at the top." }, "in_use": { "type": "boolean", "description": "false when the unit is archived and no longer offered." } } } }, "positions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "code": { "type": [ "string", "null" ] }, "in_use": { "type": "boolean", "description": "false when the position is archived." } } } }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "code": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "in_use": { "type": "boolean", "description": "false when the location is archived." } } } } } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `people:read` scope.", "x-scope": "people:read" } }, "/people/joiners": { "post": { "operationId": "postPeopleJoinersJoin", "summary": "Add a joiner (from their start date)", "tags": [ "People" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "The new person, as GET /people/{person} returns them.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The person's id in People (a UUID). Use it with /people/{person}." }, "display_name": { "type": "string", "description": "The name shown everywhere in Kanishu." }, "preferred_name": { "type": [ "string", "null" ], "description": "What they like to be called, if different." }, "work_email": { "type": "string", "description": "Their work email address; how they are matched to logins in the products." }, "employee_number": { "type": [ "string", "null" ], "description": "Your own employee number for them (e.g. from payroll or HR)." }, "type": { "type": "string", "description": "employee, contractor, external (auditor, consultant…) or other." }, "status": { "type": "string", "description": "pre_joining (joining soon), active, on_leave, leaving (last working day set) or left." }, "joining_date": { "type": "string", "format": "date", "description": "Their first working day." }, "last_working_date": { "type": [ "string", "null" ], "format": "date", "description": "Their last working day, once they are leaving; their logins are switched off after it." }, "access_end_date": { "type": [ "string", "null" ], "format": "date", "description": "When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors)." }, "department": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their department or team (id and name), from GET /people-organisation." }, "position": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their job position (id and name)." }, "location": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their office or site (id and name)." }, "manager": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string" } }, "description": "Their manager in People (id and display_name)." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `people:write` scope.", "x-scope": "people:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "access": { "type": "array", "items": { "type": "string", "maxLength": 50 }, "nullable": true, "description": "Logins they should get, as product key => role (e.g. {\"itsm\": \"agent\"}); each one waits for an approval." }, "access_end_date": { "type": "string", "nullable": true, "format": "date", "description": "When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors)." }, "display_name": { "type": "string", "maxLength": 255, "description": "The name shown everywhere in Kanishu." }, "employee_number": { "type": "string", "nullable": true, "maxLength": 50, "description": "Your own employee number for them (e.g. from payroll or HR)." }, "employment_status": { "type": "string", "enum": [ "pre_joining", "active", "on_leave", "leaving", "left" ], "description": "pre_joining (joining soon), active, on_leave, leaving (last working day set) or left." }, "joining_date": { "type": "string", "nullable": true, "format": "date", "description": "Their first working day." }, "location_id": { "type": "string", "nullable": true, "format": "uuid" }, "manager_person_id": { "type": "string", "nullable": true, "format": "uuid", "description": "The manager's People id." }, "org_unit_id": { "type": "string", "nullable": true, "format": "uuid", "description": "The department or team id, from GET /people-organisation." }, "person_type": { "type": "string", "enum": [ "employee", "contractor", "external", "other" ], "description": "employee, contractor, external (auditor, consultant…) or other." }, "position_id": { "type": "string", "nullable": true, "format": "uuid" }, "preferred_name": { "type": "string", "nullable": true, "maxLength": 255, "description": "What they like to be called, if different." }, "start_date": { "type": "string", "format": "date", "description": "Their first working day; their logins are prepared for it." }, "work_email": { "type": "string", "nullable": true, "format": "email", "maxLength": 255, "description": "Their work email address; how they are matched to logins in the products." } }, "required": [ "display_name", "start_date" ] } } } } } }, "/people/{person}": { "get": { "operationId": "getPeopleShow", "summary": "Get one of people", "tags": [ "People" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "person", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "fields", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back." } ], "responses": { "200": { "description": "OK. The record is in `data`, with its version in the `ETag` header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The person's id in People (a UUID). Use it with /people/{person}." }, "display_name": { "type": "string", "description": "The name shown everywhere in Kanishu." }, "preferred_name": { "type": [ "string", "null" ], "description": "What they like to be called, if different." }, "work_email": { "type": "string", "description": "Their work email address; how they are matched to logins in the products." }, "employee_number": { "type": [ "string", "null" ], "description": "Your own employee number for them (e.g. from payroll or HR)." }, "type": { "type": "string", "description": "employee, contractor, external (auditor, consultant…) or other." }, "status": { "type": "string", "description": "pre_joining (joining soon), active, on_leave, leaving (last working day set) or left." }, "joining_date": { "type": "string", "format": "date", "description": "Their first working day." }, "last_working_date": { "type": [ "string", "null" ], "format": "date", "description": "Their last working day, once they are leaving; their logins are switched off after it." }, "access_end_date": { "type": [ "string", "null" ], "format": "date", "description": "When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors)." }, "department": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their department or team (id and name), from GET /people-organisation." }, "position": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their job position (id and name)." }, "location": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their office or site (id and name)." }, "manager": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string" } }, "description": "Their manager in People (id and display_name)." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `people:read` scope.", "x-scope": "people:read" }, "patch": { "operationId": "patchPeopleUpdate", "summary": "Change one of people", "tags": [ "People" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "person", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "OK. The record is in `data`, with its version in the `ETag` header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The person's id in People (a UUID). Use it with /people/{person}." }, "display_name": { "type": "string", "description": "The name shown everywhere in Kanishu." }, "preferred_name": { "type": [ "string", "null" ], "description": "What they like to be called, if different." }, "work_email": { "type": "string", "description": "Their work email address; how they are matched to logins in the products." }, "employee_number": { "type": [ "string", "null" ], "description": "Your own employee number for them (e.g. from payroll or HR)." }, "type": { "type": "string", "description": "employee, contractor, external (auditor, consultant…) or other." }, "status": { "type": "string", "description": "pre_joining (joining soon), active, on_leave, leaving (last working day set) or left." }, "joining_date": { "type": "string", "format": "date", "description": "Their first working day." }, "last_working_date": { "type": [ "string", "null" ], "format": "date", "description": "Their last working day, once they are leaving; their logins are switched off after it." }, "access_end_date": { "type": [ "string", "null" ], "format": "date", "description": "When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors)." }, "department": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their department or team (id and name), from GET /people-organisation." }, "position": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their job position (id and name)." }, "location": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their office or site (id and name)." }, "manager": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string" } }, "description": "Their manager in People (id and display_name)." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "412": { "$ref": "#/components/responses/E412" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `people:write` scope.", "x-scope": "people:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "access_end_date": { "type": "string", "nullable": true, "format": "date", "description": "When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors)." }, "display_name": { "type": "string", "maxLength": 255, "description": "The name shown everywhere in Kanishu." }, "employee_number": { "type": "string", "nullable": true, "maxLength": 50, "description": "Your own employee number for them (e.g. from payroll or HR)." }, "employment_status": { "type": "string", "enum": [ "pre_joining", "active", "on_leave", "leaving", "left" ], "description": "pre_joining (joining soon), active, on_leave, leaving (last working day set) or left." }, "joining_date": { "type": "string", "nullable": true, "format": "date", "description": "Their first working day." }, "location_id": { "type": "string", "nullable": true, "format": "uuid" }, "manager_person_id": { "type": "string", "nullable": true, "format": "uuid", "description": "The manager's People id." }, "org_unit_id": { "type": "string", "nullable": true, "format": "uuid", "description": "The department or team id, from GET /people-organisation." }, "person_type": { "type": "string", "enum": [ "employee", "contractor", "external", "other" ], "description": "employee, contractor, external (auditor, consultant…) or other." }, "position_id": { "type": "string", "nullable": true, "format": "uuid" }, "preferred_name": { "type": "string", "nullable": true, "maxLength": 255, "description": "What they like to be called, if different." }, "work_email": { "type": "string", "nullable": true, "format": "email", "maxLength": 255, "description": "Their work email address; how they are matched to logins in the products." } } } } } } } }, "/people/{person}/leave": { "post": { "operationId": "postPeopleLeaveLeave", "summary": "Record a leaver (logins switched off after the last working day, or now if urgent)", "tags": [ "People" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "person", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The person, as GET /people/{person} returns them.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The person's id in People (a UUID). Use it with /people/{person}." }, "display_name": { "type": "string", "description": "The name shown everywhere in Kanishu." }, "preferred_name": { "type": [ "string", "null" ], "description": "What they like to be called, if different." }, "work_email": { "type": "string", "description": "Their work email address; how they are matched to logins in the products." }, "employee_number": { "type": [ "string", "null" ], "description": "Your own employee number for them (e.g. from payroll or HR)." }, "type": { "type": "string", "description": "employee, contractor, external (auditor, consultant…) or other." }, "status": { "type": "string", "description": "pre_joining (joining soon), active, on_leave, leaving (last working day set) or left." }, "joining_date": { "type": "string", "format": "date", "description": "Their first working day." }, "last_working_date": { "type": [ "string", "null" ], "format": "date", "description": "Their last working day, once they are leaving; their logins are switched off after it." }, "access_end_date": { "type": [ "string", "null" ], "format": "date", "description": "When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors)." }, "department": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their department or team (id and name), from GET /people-organisation." }, "position": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their job position (id and name)." }, "location": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their office or site (id and name)." }, "manager": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string" } }, "description": "Their manager in People (id and display_name)." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `people:write` scope.", "x-scope": "people:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "last_working_date": { "type": "string", "format": "date", "description": "Their last working day, once they are leaving; their logins are switched off after it." }, "reason": { "type": "string", "nullable": true, "maxLength": 500, "description": "Why they are leaving (kept in People's History)." }, "urgent": { "type": "boolean", "description": "true to switch their logins off now instead of after the last working day." } }, "required": [ "last_working_date" ] } } } } } }, "/people/{person}/move": { "post": { "operationId": "postPeopleMoveMove", "summary": "Move a person (department, manager, position or location) from a date", "tags": [ "People" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "person", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The person, as GET /people/{person} returns them.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The person's id in People (a UUID). Use it with /people/{person}." }, "display_name": { "type": "string", "description": "The name shown everywhere in Kanishu." }, "preferred_name": { "type": [ "string", "null" ], "description": "What they like to be called, if different." }, "work_email": { "type": "string", "description": "Their work email address; how they are matched to logins in the products." }, "employee_number": { "type": [ "string", "null" ], "description": "Your own employee number for them (e.g. from payroll or HR)." }, "type": { "type": "string", "description": "employee, contractor, external (auditor, consultant…) or other." }, "status": { "type": "string", "description": "pre_joining (joining soon), active, on_leave, leaving (last working day set) or left." }, "joining_date": { "type": "string", "format": "date", "description": "Their first working day." }, "last_working_date": { "type": [ "string", "null" ], "format": "date", "description": "Their last working day, once they are leaving; their logins are switched off after it." }, "access_end_date": { "type": [ "string", "null" ], "format": "date", "description": "When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors)." }, "department": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their department or team (id and name), from GET /people-organisation." }, "position": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their job position (id and name)." }, "location": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their office or site (id and name)." }, "manager": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string" } }, "description": "Their manager in People (id and display_name)." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `people:write` scope.", "x-scope": "people:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "department_id": { "type": "string", "nullable": true, "format": "uuid", "description": "The department or team they move to, from GET /people-organisation." }, "effective_date": { "type": "string", "format": "date", "description": "The date the move takes effect." }, "location_id": { "type": "string", "nullable": true, "format": "uuid" }, "manager_id": { "type": "string", "nullable": true, "format": "uuid", "description": "Their new manager's People id." }, "position_id": { "type": "string", "nullable": true, "format": "uuid" } }, "required": [ "effective_date" ] } } } } } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "A token from API Access in the product. Never put it in a URL." } }, "parameters": { "RequestId": { "name": "X-Request-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9-]{1,64}$" }, "description": "Your id for this call; echoed back. Generated when absent." }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9-]{8,100}$" }, "description": "Makes a POST safe to retry: the first answer is kept for 24 hours." }, "IfMatch": { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The ETag you read. The change is refused with 412 version_conflict if the record changed since." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "request_id" ], "properties": { "code": { "type": "string", "enum": [ "unauthenticated", "invalid_token", "bad_signature", "token_in_url", "session_expired", "ip_not_allowed", "invalid_scope", "forbidden", "forbidden_organization", "not_supported", "feature_not_included", "subscription_read_only", "subscription_suspended", "limit_reached", "rate_limited", "quota_exceeded", "daily_limit_exceeded", "bad_request", "invalid_request", "request_failed", "validation_failed", "missing_organization_id", "not_eligible", "approval_refused", "incomplete", "activation_failed", "idempotency_key_reused", "idempotency_in_progress", "invalid_filter", "invalid_sort", "invalid_include", "invalid_fields", "not_found", "method_not_allowed", "conflict", "duplicate", "exists", "version_conflict", "payload_too_large", "unsupported_media_type", "product_maintenance", "product_disabled", "platform_tenant_not_configured", "unavailable", "server_error" ] }, "message": { "type": "string" }, "details": { "type": "object" }, "request_id": { "type": "string" } } } } }, "ListMeta": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "last_page": { "type": "integer" } } } }, "responses": { "E400": { "description": "Bad request (invalid_filter, invalid_sort, invalid_fields, bad_request).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E401": { "description": "No or bad token (unauthenticated, invalid_token).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E402": { "description": "Plan limit or feature (limit_reached, feature_not_included).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E403": { "description": "Not allowed (invalid_scope, forbidden, forbidden_organization, ip_not_allowed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E409": { "description": "Conflict (duplicate, idempotency_key_reused, idempotency_in_progress).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E412": { "description": "The record changed since you read it (version_conflict).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E422": { "description": "Validation failed; details.fields lists each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E429": { "description": "Too many calls (rate_limited, daily quota). See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E500": { "description": "Server error. Quote request_id to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E503": { "description": "Unavailable (maintenance).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }