--- title: "Create a lead" method: POST path: "/entities/Leads" tags: ["Lead & Opportunity"] --- # Create a lead `POST /entities/Leads` ## Request - Base URL: `https://us-east.api.coevera.com/api/v100/rest/spaces/your_space_id` - URL: `https://us-east.api.coevera.com/api/v100/rest/spaces/your_space_id/entities/Leads` - Auth: HTTP basic - TypeScript: (a function with typed inputs; its response is checked against the schema) Creates one lead and answers 201 with the record. `name` is required, and a sales unit through `owner_id` or `unit_id`. ## Query parameters - `validation-level` integer ## Request body - CreateLeadInput: Field values of a new Lead record. - `modified` string, date-time: Last modification time. - `created` string, date-time: Creation time. - `currency_exchange_rates_list_id` string, uuid: Id of the currency exchange rate list applied to this lead. - `description` string: Free-form description of the lead. - `is_archived` boolean: True when the lead has been archived (lost). Archived leads remain readable but are hidden from active lists and cannot be edited until reactivated. - `label_flag` string: User-set colored flag used to highlight the lead in lists and reports. - `last_ai_buying_center_applied` string, date-time: Time when an AI-suggested buying center was last applied to this lead. - `lead_source_id` string, uuid: Id of the lead source recording how the lead originated (e.g. Website, Referral, Trade Show). - `lead_type_id` string, uuid: Id of the lead type that classifies the lead and drives which form, fields and lead process apply. - `name` string, required: Name of the entity and its default text representation. - `owner_id` string, uuid: Id of the lead owner; a create needs `owner_id` or `unit_id`, and with `owner_id` the lead takes the owner's sales unit. Without either the API answers HTTP 422. - `quick_account_email` string: Free-text company email captured at lead creation when no Account record has been linked yet. - `quick_account_name` string: Free-text company name captured at lead creation when no Account record has been linked yet. - `quick_account_phone` string: Free-text company phone captured at lead creation when no Account record has been linked yet. - `quick_contact_name` string: Free-text contact name captured at lead creation when no Contact record has been linked yet. - `quick_email` string: Free-text contact email captured at lead creation when no Contact record has been linked yet. - `quick_phone` string: Free-text contact phone captured at lead creation when no Contact record has been linked yet. - `ranking` integer: Qualitative ranking score (1-10) the user assigns to indicate the strength of the lead. - `reason_of_close_description` string: Free-form note explaining why the lead was archived (lost). Captured alongside reason_of_close. - `reason_of_close_id` string, uuid: Id of the reason recorded when the lead is archived (lost), or empty when none was given. - `share_mode` 0 | 1 | 2 | 3: Sharing model applied on top of the owner/unit visibility (e.g. shared with selected sales units or selected users). The matching sharing_units / sharing_clients lists control who is granted access. Integer enum value: 0 - Standard, 1 - Private, 2 - AllView, 3 - AllEdit - `step_id` string, uuid: Id of the lead process step. - `unit_id` string, uuid: Id of the sales unit; a create needs `owner_id` or `unit_id`, and with `unit_id` alone the lead waits unassigned in that unit. - `revision` integer: Revision when entity was lastly changed. - `contact_relations` object[]: Contacts linked to this lead, including their roles and org-chart positions. - `id` string, uuid: Id of the related LeadOpptyContactRelation record. - `account_relations` object[]: Accounts linked to this lead, including the primary-account flag. - `id` string, uuid: Id of the related LeadOpptyAccountRelation record. - `sharing_units` object[]: Sales units that have been granted shared access to this lead. Editable only when share_mode allows unit sharing. - `id` string, uuid: Id of the related LeadOpptySharingSalesUnitRelation record. - `sharing_clients` object[]: Users that have been granted shared access to this lead. Editable only when share_mode allows user sharing. - `id` string, uuid: Id of the related LeadOpptySharingClientRelation record. - `documents` object[]: Documents linked to this lead. - `id` string, uuid: Id of the related CloudObjectRelation record. - `tags` object[]: Tag labels applied to this lead. - `id` string, uuid: Id of the related TagRelation record. - `static_profiles` object[]: Saved view profiles this lead currently matches. - `id` string, uuid: Id of the related ProfileRelation record. - `lost_date` string, date-time: Timestamp of when the lead was archived (lost). Setting it adjusts the underlying loss event; empty for leads that have not been archived. ## Response `201` The created Lead record. - object - `success` boolean: True when the request succeeded; false on error. - `data` Lead: Potential sale in its early stage that moves through a lead process until it is qualified into an opportunity or lost. - `is_delete_protected` boolean, required: True when the record is protected against deletion because it must always exist in the space. Deleting a record that is not protected can still fail on other checks. Read-only. - `id` string, uuid, required: Unique identifier of entity. - `is_deleted` boolean: Specifies if the entity is considered deleted. - `modified` string, date-time: Last modification time. - `created` string, date-time: Creation time. - `currency_exchange_rates_list` string, uri: Currency exchange rate list used to convert monetary fields linked to this lead. Empty to inherit the team space default. Related CurrencyExchangeRatesList record, returned as the URI of the record. With the 'expand' parameter the full record is returned instead; see 'CurrencyExchangeRatesList' for its fields. - `lead_source` string, uri: How the lead originated (e.g. Website, Referral, Trade Show). Configurable per team space. Related Data record, returned as the URI of the record. With the 'expand' parameter the full record is returned instead; see 'Data' for its fields. - `lead_type` string, uri, required: Lead type that classifies this lead. Lead types are configurable per team space and drive which form, fields and lead process apply. Related LeadType record, returned as the URI of the record. With the 'expand' parameter the full record is returned instead; see 'LeadType' for its fields. - `owner` string, uri: Sales user who owns this lead. May be empty when the lead is unassigned and available for take-over. Related Client record, returned as the URI of the record. With the 'expand' parameter the full record is returned instead; see 'Client' for its fields. - `reason_of_close` string, uri: Configurable reason recorded when the lead is archived (lost). Required when the lost form mandates it. Related Data record, returned as the URI of the record. With the 'expand' parameter the full record is returned instead; see 'Data' for its fields. - `step` string, uri, required: Step in the lead process the lead is currently in. Related Step record, returned as the URI of the record. With the 'expand' parameter the full record is returned instead; see 'Step' for its fields. - `unit` string, uri, required: Sales unit this lead is assigned to. Determines which team members can see the record under unit-based sharing. Related SalesUnit record, returned as the URI of the record. With the 'expand' parameter the full record is returned instead; see 'SalesUnit' for its fields. - `currency_exchange_rates_list_id` string, uuid: Id of the currency exchange rate list applied to this lead. - `description` string: Free-form description of the lead. - `is_archived` boolean: True when the lead has been archived (lost). Archived leads remain readable but are hidden from active lists and cannot be edited until reactivated. - `label_flag` string: User-set colored flag used to highlight the lead in lists and reports. - `last_ai_buying_center_applied` string, date-time: Time when an AI-suggested buying center was last applied to this lead. - `lead_source_id` string, uuid: Id of the lead source recording how the lead originated (e.g. Website, Referral, Trade Show). - `lead_type_id` string, uuid: Id of the lead type that classifies the lead and drives which form, fields and lead process apply. - `name` string, required: Name of the entity and its default text representation. - `owner_id` string, uuid: Id of the lead owner; a create needs `owner_id` or `unit_id`. - `quick_account_email` string: Free-text company email captured at lead creation when no Account record has been linked yet. - `quick_account_name` string: Free-text company name captured at lead creation when no Account record has been linked yet. - `quick_account_phone` string: Free-text company phone captured at lead creation when no Account record has been linked yet. - `quick_contact_name` string: Free-text contact name captured at lead creation when no Contact record has been linked yet. - `quick_email` string: Free-text contact email captured at lead creation when no Contact record has been linked yet. - `quick_phone` string: Free-text contact phone captured at lead creation when no Contact record has been linked yet. - `ranking` integer: Qualitative ranking score (1-10) the user assigns to indicate the strength of the lead. - `reason_of_close_description` string: Free-form note explaining why the lead was archived (lost). Captured alongside reason_of_close. - `reason_of_close_id` string, uuid: Id of the reason recorded when the lead is archived (lost), or empty when none was given. - `share_mode` 0 | 1 | 2 | 3: Sharing model applied on top of the owner/unit visibility (e.g. shared with selected sales units or selected users). The matching sharing_units / sharing_clients lists control who is granted access. Integer enum value: 0 - Standard, 1 - Private, 2 - AllView, 3 - AllEdit - `step_id` string, uuid: Id of the lead process step. - `table_name` string, required: Discriminator identifying the concrete record type — always "lead" for Lead records. Read-only; useful when consuming polymorphic LeadOppty results. - `unit_id` string, uuid: Id of the sales unit; a create needs `owner_id` or `unit_id`. - `revision` integer: Revision when entity was lastly changed. - `primary_contact` string, uri: Primary contact of this lead. Set automatically from the contact relation marked as primary. Related Contact record, returned as the URI of the record. With the 'expand' parameter the full record is returned instead; see 'Contact' for its fields. - `primary_account` string, uri: Primary account of this lead. Set automatically from the account relation marked as primary. Related Account record, returned as the URI of the record. With the 'expand' parameter the full record is returned instead; see 'Account' for its fields. - `contact_relations` string[]: Contacts linked to this lead, including their roles and org-chart positions. - `account_relations` string[]: Accounts linked to this lead, including the primary-account flag. - `status` 1 | 2, required: Current status of the lead (Open, Lost, Qualified). Read-only; derived from the archived flag and lifecycle events. Integer enum value: 1 - Open, 2 - Lost - `sharing_units` string[]: Sales units that have been granted shared access to this lead. Editable only when share_mode allows unit sharing. - `sharing_clients` string[]: Users that have been granted shared access to this lead. Editable only when share_mode allows user sharing. - `documents` string[]: Documents linked to this lead. - `tags` string[]: Tag labels applied to this lead. - `static_profiles` string[]: Saved view profiles this lead currently matches. - `qualify_date` string, date-time: Timestamp of when the lead was qualified, taken from the matching KPI event. Empty for leads that have not been qualified. Read-only. - `days_in_step` integer, required: Number of days the lead has been sitting in its current pipeline step. Read-only; computed by Coevera from the most recent move event. - `is_favorite` boolean, required: True when the current authenticated user has marked this lead as favorite. Per-user. - `lost_date` string, date-time: Timestamp of when the lead was archived (lost). Setting it adjusts the underlying loss event; empty for leads that have not been archived. - `formatted_name` string, required: Display version of the lead name, used in lists and references. - `scoring` object: Lead scoring summary, combining the percentile and current scoring state. Read-only; computed by Coevera. - `modified_by_user` string, date-time: Timestamp of the most recent modification made by an end user (excluding system changes). Read-only; computed by Coevera. ## Other responses - `400`: Bad request: a bad or unknown parameter (codes 117, 118), a missing permission (code 50), conflicting data (code 2002) or any other API error. The REST API answers 400 where others answer 403 or 409; check `code`. - `401`: Not authenticated: missing or wrong credentials, a credential of another space, or an expired token (code 401, ERROR_UNAUTHORIZED). - `422`: Validation failed (code 40000, with the failing fields) or a required parameter is missing (code 119). By default one failed item fails a whole batch and nothing is written. - `429`: Too many requests (code 182). Wait for the seconds in Retry-After, then retry. - `500`: Unexpected server error (code 1000, ERROR_UNKNOWN). --- [API](https://skmtc.dev/coevera/apis/coevera-crm-api.md) - [All operations](https://skmtc.dev/coevera/apis/coevera-crm-api/llms.txt) - [OpenAPI document](https://skmtc.dev/coevera/apis/coevera-crm-api/revisions/40ebbc83f179?raw)