{ "openapi": "3.1.0", "info": { "title": "Icypeas API", "version": "1.16.0", "description": "Icypeas API documentation. Find and verify professional email addresses, scan domains, scrape profiles and companies and search a B2B lead database, with or without code.\n\nSearches are asynchronous: start one, then read its result with `POST /bulk-single-searchs/read` or receive it on a webhook. Human-friendly docs: https://api-doc.icypeas.com", "contact": { "name": "Icypeas support", "email": "support@icypeas.com", "url": "https://api-doc.icypeas.com/support" } }, "externalDocs": { "url": "https://api-doc.icypeas.com", "description": "Icypeas API documentation" }, "servers": [ { "url": "https://app.icypeas.com/api" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Results", "externalDocs": { "url": "https://api-doc.icypeas.com/reference/get-results" } }, { "name": "Emails", "externalDocs": { "url": "https://api-doc.icypeas.com/reference/email-verification" } }, { "name": "Lead database", "externalDocs": { "url": "https://api-doc.icypeas.com/reference/find-people" } }, { "name": "Profiles & companies", "externalDocs": { "url": "https://api-doc.icypeas.com/reference/scrape-profile" } }, { "name": "Account", "externalDocs": { "url": "https://api-doc.icypeas.com/reference/subscription" } } ], "paths": { "/search-files/read": { "post": { "operationId": "bulkSearchProgress", "summary": "Bulk search progress", "tags": [ "Results" ], "externalDocs": { "url": "https://api-doc.icypeas.com/reference/bulk-files", "description": "Documentation: Bulk search progress and stats" }, "description": "Get all your bulk searches.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "number", "description": "Limit of files to fetch. Rule: default value is 10, max value is 50." }, "file": { "type": "string", "description": "If you want to get a specifc bulk, please use this field with your file id" }, "status": { "type": "string", "description": "If you want to fetch only bulk searches that are in progress or that are done Rule: has to be either 'in_progress' or 'done'." }, "next": { "type": "boolean", "description": "If you want to paginate, use this field. true = next page | false = previous page" }, "sorts": { "type": "array", "items": { "type": "object", "properties": { "creationDate": { "type": "number", "description": "I don't know what to write here. " } }, "required": [ "creationDate" ] }, "description": "Array used to paginate your files, it is this item you need to pass in your requests if you want to paginate further" } } }, "examples": { "bulk-search-progress-1": { "summary": "Bulk search progress", "value": { "limit": 2 } } } } } }, "responses": { "200": { "description": "Response when your input is good. / Response when there are validation errors.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "success": { "type": "boolean", "description": "This field lets you know if your request was successful" }, "files": { "type": "array", "items": { "type": "object", "properties": { "file": { "type": "string", "description": "Unique ID of your file" }, "system": { "type": "object", "properties": { "createdAt": { "type": "string", "description": "ISO String Date representing the creation date of the search." }, "modifiedAt": { "type": "string", "description": "ISO String Date representing the last modification date of the search." } }, "required": [ "createdAt", "modifiedAt" ], "description": "Information concerning the search." }, "name": { "type": "string", "description": "Name of your file" }, "found": { "type": "number", "description": "Number of found items in your bulk search" }, "done": { "type": "number", "description": "Number of items that are already processed" }, "aborted": { "type": "number", "description": "Number of items that you have cancelled" }, "credits-missing": { "type": "number", "description": "Number of items that have been cancelled by the system because you do not have enough credits" }, "in-progress": { "type": "number", "description": "Number of items that are currently in progress" }, "bad-input": { "type": "number", "description": "Number of items that cannot be analyzed because they are invalid (missing data, ...)" }, "total": { "type": "number", "description": "Total number of items in your bulk search" }, "finished": { "type": "boolean", "description": "Set to true when the bulk search has been entirely processed" }, "task": { "type": "string", "description": "Task for the bulk search (email-verification, domain-search, ...)" }, "generationInProgress": { "type": "boolean", "description": "Exposed for internal use only, please do not use" }, "exported": { "type": "boolean", "description": "Exposed for internal use only, please do not use" } }, "required": [ "file", "system", "name", "found", "done", "aborted", "credits-missing", "in-progress", "bad-input", "total", "finished", "task", "generationInProgress", "exported" ] }, "description": "Array of your files" }, "sorts": { "type": "array", "items": { "type": "object", "properties": { "creationDate": { "type": "number", "description": "Unix timestamp" } }, "required": [ "creationDate" ] }, "description": "Array used to paginate your files, it is this item you need to pass in your requests if you want to paginate further" }, "total": { "type": "number", "description": "Total number of bulk searches" } }, "required": [ "success", "files", "total" ] }, { "type": "object", "description": "Returned with HTTP 200 when the request body is invalid. See the `validationErrors` array for every problem.", "properties": { "success": { "type": "boolean", "const": false }, "validationErrors": { "type": "array", "items": { "type": "object", "properties": { "expected": { "description": "What the API expected (for example `string`)." }, "actual": { "description": "The value that was received." }, "type": { "type": "string", "description": "Validation error type, for example `required`." }, "field": { "type": "string", "description": "The field in error." }, "message": { "type": "string", "description": "Stable machine-readable code, for example `validation_required`." } } } } } } ] }, "examples": { "success": { "summary": "Response when your input is good.", "value": { "success": true, "files": [ { "file": "#FILEID_1#", "system": { "createdAt": "2023-01-01T12:00:00.000Z", "modifiedAt": "2023-01-01T12:00:00.000Z" }, "name": "Last File", "found": 250, "done": 300, "aborted": 0, "credits-missing": 0, "in-progress": 0, "bad-input": 0, "total": 300, "generationInProgress": true, "exported": false, "task": "email-verification", "finished": true }, { "file": "#FILEID_2#", "system": { "createdAt": "2023-01-01T11:00:00.000Z", "modifiedAt": "2023-01-01T11:00:00.000Z" }, "name": "First File", "found": 2500, "done": 2600, "aborted": 0, "bad-input": 50, "in-progress": 350, "credits-missing": 0, "total": 3000, "generationInProgress": false, "exported": false, "task": "email-search", "finished": false } ], "total": 10, "sorts": [ [ 1678195083294 ], [ 1678194871170 ] ] } }, "validationError": { "summary": "Response when there are validation errors.", "value": { "validationErrors": [ { "expected": "string", "type": "required", "field": "user", "message": "validation_required" } ], "success": false } } } } } }, "401": { "description": "Response when we could not authenticate you.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error name" }, "status": { "type": "number", "description": "HTTP error code" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message", "error", "status", "code" ] }, "examples": { "success": { "summary": "Response when we could not authenticate you.", "value": { "message": "Unauthorized access.", "error": "UnauthorizedAccessError", "status": 401, "code": "unauthorized_access_error" } } } } } }, "429": { "description": "Error received when rate limit is exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error name" }, "status": { "type": "number", "description": "HTTP error code" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message", "error", "status", "code" ] }, "examples": { "success": { "summary": "Error received when rate limit is exceeded", "value": { "message": "You have exceeded the max number of requests per minute.", "error": "RateLimitExceededError", "status": 429, "code": "rate_limit_exceeded_error" } } } } } } } } }, "/bulk-search": { "post": { "operationId": "bulkSearch", "summary": "Bulk search", "tags": [ "Emails" ], "externalDocs": { "url": "https://api-doc.icypeas.com/reference/bulk-search", "description": "Documentation: Bulk search: find or verify up to 5,000 emails per call" }, "description": "Start a new bulk search from the API.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the bulk search you are creating." }, "task": { "type": "string", "description": "The type of bulk search you want to do. Rule: has to be either 'domain-search', 'email-search' or 'email-verification'." }, "data": { "type": "array", "items": { "type": "array", "items": {}, "description": "Each row you want to be analyzed. If you are doing an 'email-search' you should have 3 items in each row.In other modes it's only 1 item." }, "description": "Emails, prospects or domains you want to analyze." }, "custom": { "type": "object", "properties": { "webhookUrlItem": { "type": "string", "format": "uri", "description": "Custom webhook to be called each time a row is processed. It receives the result of that row. See the 'Search item processed' webhook." }, "webhookUrlBulkDone": { "type": "string", "format": "uri", "description": "Custom webhook to be called when the whole bulk search is processed. It receives the statistics of the bulk search (and the results if includeResultsInWebhook is true). See the 'Bulk search done' webhook." }, "externalIds": { "type": "array", "items": {}, "description": "Array of strings. Each id should correspond to each row in your data array. So, if provided, the length of externalIds should match the length of your data array. We do not check for the uniqueness of your IDs, you are responsible of that." }, "includeResultsInWebhook": { "type": "boolean", "description": "If provided, we add the results of your search directly in the webhook called at the end of the bulk. Please if your bulk search has more than 1000 items, make sure you have properly configured your webhook and server to accept large POST requests. If not, do not use this option." } }, "description": "Custom object for passing custom webhooks and/or custom ids that will be added to each row" } }, "required": [ "name", "task", "data" ] }, "examples": { "bulk-search-1": { "summary": "Bulk search", "value": { "name": "Icypeas Prospects to analyze", "task": "email-search", "data": [ [ "John", "Doe", "icypeas.com" ], [ "John", "Doe", "Icypeas" ] ] } } } } } }, "responses": { "200": { "description": "Response when your input is good. / Response when there are validation errors.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "success": { "type": "boolean", "description": "This field lets you know if your request was successful" }, "status": { "type": "string", "description": "The status of the bulk search." }, "file": { "type": "string", "description": "The new file's id." } }, "required": [ "success", "status", "file" ] }, { "type": "object", "description": "Returned with HTTP 200 when the request body is invalid. See the `validationErrors` array for every problem.", "properties": { "success": { "type": "boolean", "const": false }, "validationErrors": { "type": "array", "items": { "type": "object", "properties": { "expected": { "description": "What the API expected (for example `string`)." }, "actual": { "description": "The value that was received." }, "type": { "type": "string", "description": "Validation error type, for example `required`." }, "field": { "type": "string", "description": "The field in error." }, "message": { "type": "string", "description": "Stable machine-readable code, for example `validation_required`." } } } } } } ] }, "examples": { "success": { "summary": "Response when your input is good.", "value": { "success": true, "status": "in_progress", "file": "#FILEID#" } }, "validationError": { "summary": "Response when there are validation errors.", "value": { "validationErrors": [ { "expected": "string", "type": "required", "field": "user", "message": "validation_required" } ], "success": false } } } } } }, "401": { "description": "Response when we could not authenticate you.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error name" }, "status": { "type": "number", "description": "HTTP error code" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message", "error", "status", "code" ] }, "examples": { "success": { "summary": "Response when we could not authenticate you.", "value": { "message": "Unauthorized access.", "error": "UnauthorizedAccessError", "status": 401, "code": "unauthorized_access_error" } } } } } }, "429": { "description": "Error received when rate limit is exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error name" }, "status": { "type": "number", "description": "HTTP error code" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message", "error", "status", "code" ] }, "examples": { "success": { "summary": "Error received when rate limit is exceeded", "value": { "message": "You have exceeded the max number of requests per minute.", "error": "RateLimitExceededError", "status": 429, "code": "rate_limit_exceeded_error" } } } } } } } } }, "/domain-search": { "post": { "operationId": "domainSearch", "summary": "Domain search", "tags": [ "Emails" ], "externalDocs": { "url": "https://api-doc.icypeas.com/reference/domain-search", "description": "Documentation: Domain search: find the role-based emails of a company" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domainOrCompany": { "type": "string", "description": "The domain or the company name you want to scan." }, "custom": { "type": "object", "properties": { "webhookUrl": { "type": "string", "format": "uri", "description": "A URL Icypeas calls with the result as soon as this search is done. See the 'Search item processed' webhook." }, "externalId": { "type": "string", "description": "Your own id for this search (for example a CRM id). It comes back with the result and in webhooks. Icypeas doesn't check that it's unique." } }, "description": "Optional settings for this search: a webhook URL and/or your own id." } }, "required": [ "domainOrCompany" ] }, "examples": { "domain-search-1": { "summary": "Domain search", "value": { "domainOrCompany": "icypeas.com" } } } } } }, "responses": { "200": { "description": "Response when your input is good. / Response when there are validation errors", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "success": { "type": "boolean", "description": "true means that your search has been taken into account" }, "item": { "type": "object", "properties": { "_id": { "type": "string", "description": "Search id to follow its progression" }, "status": { "type": "string", "description": "Status of this search (NONE right after creation). See the Result statuses page." } }, "required": [ "_id", "status" ], "description": "Information about your search" } }, "required": [ "success", "item" ] }, { "type": "object", "description": "Returned with HTTP 200 when the request body is invalid. See the `validationErrors` array for every problem.", "properties": { "success": { "type": "boolean", "const": false }, "validationErrors": { "type": "array", "items": { "type": "object", "properties": { "expected": { "description": "What the API expected (for example `string`)." }, "actual": { "description": "The value that was received." }, "type": { "type": "string", "description": "Validation error type, for example `required`." }, "field": { "type": "string", "description": "The field in error." }, "message": { "type": "string", "description": "Stable machine-readable code, for example `validation_required`." } } } } } } ] }, "examples": { "success": { "summary": "Response when your input is good.", "value": { "success": true, "item": { "_id": "#YOUR_SEARCH_ID#", "status": "NONE" } } }, "validationError": { "summary": "Response when there are validation errors", "value": { "validationErrors": [ { "expected": "string", "type": "required", "field": "domainOrCompany", "message": "validation_required" } ], "success": false } } } } } }, "401": { "description": "Response when we could not authenticate you.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error name" }, "status": { "type": "number", "description": "HTTP error code" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message", "error", "status", "code" ] }, "examples": { "success": { "summary": "Response when we could not authenticate you.", "value": { "message": "Unauthorized access.", "error": "UnauthorizedAccessError", "status": 401, "code": "unauthorized_access_error" } } } } } }, "429": { "description": "Error received when rate limit is exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error name" }, "status": { "type": "number", "description": "HTTP error code" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message", "error", "status", "code" ] }, "examples": { "success": { "summary": "Error received when rate limit is exceeded", "value": { "message": "You have exceeded the max number of requests per minute.", "error": "RateLimitExceededError", "status": 429, "code": "rate_limit_exceeded_error" } } } } } } } } }, "/email-search": { "post": { "operationId": "emailSearch", "summary": "Email search", "tags": [ "Emails" ], "externalDocs": { "url": "https://api-doc.icypeas.com/reference/email-search", "description": "Documentation: Email search: find a professional email" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "firstname": { "type": "string", "description": "The firstname of the person you want to find. Rule: can be empty if a lastname is set." }, "lastname": { "type": "string", "description": "The lastname of the person you want to find. Rule: can be empty if a firstname is set." }, "domainOrCompany": { "type": "string", "description": "The domain or the company name of the person you want to find." }, "custom": { "type": "object", "properties": { "webhookUrl": { "type": "string", "format": "uri", "description": "A URL Icypeas calls with the result as soon as this search is done. See the 'Search item processed' webhook." }, "externalId": { "type": "string", "description": "Your own id for this search (for example a CRM id). It comes back with the result and in webhooks. Icypeas doesn't check that it's unique." } }, "description": "Optional settings for this search: a webhook URL and/or your own id." } }, "required": [ "firstname", "lastname", "domainOrCompany" ] }, "examples": { "email-search-1": { "summary": "Email search", "value": { "firstname": "John", "lastname": "Doe", "domainOrCompany": "icypeas.com" } } } } } }, "responses": { "200": { "description": "Response when your input is good. / Response when there are validation errors.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "success": { "type": "boolean", "description": "true means that your search has been taken into account" }, "item": { "type": "object", "properties": { "_id": { "type": "string", "description": "Search id to follow its progression" }, "status": { "type": "string", "description": "Status of this search (NONE right after creation). See the Result statuses page." } }, "required": [ "_id", "status" ], "description": "Information about your search" } }, "required": [ "success", "item" ] }, { "type": "object", "description": "Returned with HTTP 200 when the request body is invalid. See the `validationErrors` array for every problem.", "properties": { "success": { "type": "boolean", "const": false }, "validationErrors": { "type": "array", "items": { "type": "object", "properties": { "expected": { "description": "What the API expected (for example `string`)." }, "actual": { "description": "The value that was received." }, "type": { "type": "string", "description": "Validation error type, for example `required`." }, "field": { "type": "string", "description": "The field in error." }, "message": { "type": "string", "description": "Stable machine-readable code, for example `validation_required`." } } } } } } ] }, "examples": { "success": { "summary": "Response when your input is good.", "value": { "success": true, "item": { "_id": "#YOUR_SEARCH_ID#", "status": "NONE" } } }, "validationError": { "summary": "Response when there are validation errors.", "value": { "validationErrors": [ { "expected": "string", "type": "required", "field": "firstname", "message": "validation_required" }, { "expected": "string", "type": "required", "field": "lastname", "message": "validation_required" }, { "expected": "string", "type": "required", "field": "domainOrCompany", "message": "validation_required" } ], "success": false } } } } } }, "401": { "description": "Response when we could not authenticate you.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error name" }, "status": { "type": "number", "description": "HTTP error code" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message", "error", "status", "code" ] }, "examples": { "success": { "summary": "Response when we could not authenticate you.", "value": { "message": "Unauthorized access.", "error": "UnauthorizedAccessError", "status": 401, "code": "unauthorized_access_error" } } } } } }, "429": { "description": "Error received when rate limit is exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error name" }, "status": { "type": "number", "description": "HTTP error code" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message", "error", "status", "code" ] }, "examples": { "success": { "summary": "Error received when rate limit is exceeded", "value": { "message": "You have exceeded the max number of requests per minute.", "error": "RateLimitExceededError", "status": 429, "code": "rate_limit_exceeded_error" } } } } } } } } }, "/email-verification": { "post": { "operationId": "emailVerification", "summary": "Email verification", "tags": [ "Emails" ], "externalDocs": { "url": "https://api-doc.icypeas.com/reference/email-verification", "description": "Documentation: Email verification: check that an email exists" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address you want to verify." }, "custom": { "type": "object", "properties": { "webhookUrl": { "type": "string", "format": "uri", "description": "A URL Icypeas calls with the result as soon as this search is done. See the 'Search item processed' webhook." }, "externalId": { "type": "string", "description": "Your own id for this search (for example a CRM id). It comes back with the result and in webhooks. Icypeas doesn't check that it's unique." } }, "description": "Optional settings for this search: a webhook URL and/or your own id." } }, "required": [ "email" ] }, "examples": { "email-verification-1": { "summary": "Email verification", "value": { "email": "example-email@icypeas.com" } } } } } }, "responses": { "200": { "description": "Response when your input is good. / Response when there are validation errors", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "success": { "type": "boolean", "description": "true means that your search has been taken into account" }, "item": { "type": "object", "properties": { "_id": { "type": "string", "description": "Search id to follow its progression" }, "status": { "type": "string", "description": "Status of this search (NONE right after creation). See the Result statuses page." } }, "required": [ "_id", "status" ], "description": "Information about your search" } }, "required": [ "success", "item" ] }, { "type": "object", "description": "Returned with HTTP 200 when the request body is invalid. See the `validationErrors` array for every problem.", "properties": { "success": { "type": "boolean", "const": false }, "validationErrors": { "type": "array", "items": { "type": "object", "properties": { "expected": { "description": "What the API expected (for example `string`)." }, "actual": { "description": "The value that was received." }, "type": { "type": "string", "description": "Validation error type, for example `required`." }, "field": { "type": "string", "description": "The field in error." }, "message": { "type": "string", "description": "Stable machine-readable code, for example `validation_required`." } } } } } } ] }, "examples": { "success": { "summary": "Response when your input is good.", "value": { "success": true, "item": { "_id": "#YOUR_SEARCH_ID#", "status": "NONE" } } }, "validationError": { "summary": "Response when there are validation errors", "value": { "validationErrors": [ { "expected": "email", "type": "required", "field": "email", "message": "validation_required" } ], "success": false } } } } } }, "401": { "description": "Response when we could not authenticate you.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error name" }, "status": { "type": "number", "description": "HTTP error code" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message", "error", "status", "code" ] }, "examples": { "success": { "summary": "Response when we could not authenticate you.", "value": { "message": "Unauthorized access.", "error": "UnauthorizedAccessError", "status": 401, "code": "unauthorized_access_error" } } } } } }, "429": { "description": "Error received when rate limit is exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error name" }, "status": { "type": "number", "description": "HTTP error code" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message", "error", "status", "code" ] }, "examples": { "success": { "summary": "Error received when rate limit is exceeded", "value": { "message": "You have exceeded the max number of requests per minute.", "error": "RateLimitExceededError", "status": 429, "code": "rate_limit_exceeded_error" } } } } } } } } }, "/find-companies/count": { "post": { "operationId": "countMatchingCompaniesFree", "summary": "Count matching companies (free)", "tags": [ "Lead database" ], "externalDocs": { "url": "https://api-doc.icypeas.com/reference/find-companies", "description": "Documentation: Find companies: search the B2B company database" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "object", "properties": {}, "description": "The query Rule: should be a valid query (see available fields above)." } }, "required": [ "query" ] } } } }, "responses": { "200": { "description": "Response when they are no errors / Response when there are validation errors.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "success": { "type": "boolean", "description": "true means that your search succeeded (no error was raised on our side)" }, "total": { "type": "number", "description": "The number of companies " } }, "required": [ "success", "total" ] }, { "type": "object", "description": "Returned with HTTP 200 when the request body is invalid. See the `validationErrors` array for every problem.", "properties": { "success": { "type": "boolean", "const": false }, "validationErrors": { "type": "array", "items": { "type": "object", "properties": { "expected": { "description": "What the API expected (for example `string`)." }, "actual": { "description": "The value that was received." }, "type": { "type": "string", "description": "Validation error type, for example `required`." }, "field": { "type": "string", "description": "The field in error." }, "message": { "type": "string", "description": "Stable machine-readable code, for example `validation_required`." } } } } } } ] }, "examples": { "success": { "summary": "Response when they are no errors", "value": { "success": true, "total": 10 } }, "validationError": { "summary": "Response when there are validation errors.", "value": { "validationErrors": [ { "expected": "object with props defined in the schema", "type": "objectStrict", "actual": { "x": 10 }, "field": "query.headcount", "message": "The object 'query.headcount' contains forbidden keys." } ], "success": false } } } } } }, "401": { "description": "Response when we could not authenticate you.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error name" }, "status": { "type": "number", "description": "HTTP error code" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message", "error", "status", "code" ] }, "examples": { "success": { "summary": "Response when we could not authenticate you.", "value": { "message": "Unauthorized access.", "error": "UnauthorizedAccessError", "status": 401, "code": "unauthorized_access_error" } } } } } }, "429": { "description": "Error received when rate limit is exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error name" }, "status": { "type": "number", "description": "HTTP error code" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message", "error", "status", "code" ] }, "examples": { "success": { "summary": "Error received when rate limit is exceeded", "value": { "message": "You have exceeded the max number of requests per minute.", "error": "RateLimitExceededError", "status": 429, "code": "rate_limit_exceeded_error" } } } } } } } } }, "/find-companies": { "post": { "operationId": "fetchMatchingCompanies", "summary": "Fetch matching companies", "tags": [ "Lead database" ], "externalDocs": { "url": "https://api-doc.icypeas.com/reference/find-companies", "description": "Documentation: Find companies: search the B2B company database" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "object", "properties": {}, "description": "The query Rule: should be a valid query (see available fields above)." }, "pagination": { "type": "object", "properties": { "token": { "type": "string", "description": "The token returned with the previous page. Valid 15 minutes; each response returns a new token with a new 15-minute validity. Rule: should be a valid pagination token." }, "size": { "type": "number", "description": "The number of companies returned per page Rule: should be a valid integer between 1 and 200.", "default": "100" } }, "required": [ "token" ], "description": "This is optional and used only if you want to retrieve more companies than the first page. Rule: should be a valid pagination object." } }, "required": [ "query" ] } } } }, "responses": { "200": { "description": "Response when no errors are sent / Response when there are validation errors.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "success": { "type": "boolean", "description": "true means that your search succeeded (no error was raised on our side)" }, "total": { "type": "number", "description": "The number of companies" }, "pagination": { "type": "object", "properties": { "token": { "type": "string", "description": "Token to request the next page. Valid 15 minutes from this response: request the next page before it expires." }, "size": { "type": "number", "description": "The number of companies returned per page", "default": "100" } }, "required": [ "token" ], "description": "This is used if you want to retrieve more companies than the first page." }, "leads": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string", "description": "Icypeas unique identifier." }, "name": { "type": "string", "description": "Company name" }, "url": { "type": "string", "description": "LinkedIn company URL." }, "urn": { "type": "string", "description": "LinkedIn company URN." }, "website": { "type": "string", "description": "Company website" }, "phone": { "type": "string", "description": "Main phone number given by the company (unnormalized, we keep what was given)" }, "industry": { "type": "string", "description": "Company industry" }, "foundedYear": { "type": "number", "description": "Company founded year (-1 when not known)" }, "specialties": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "Data value." } }, "required": [ "value" ] }, "description": "Company specialties" }, "lid": { "type": "string", "description": "LinkedIn ID (the `my-linkedin-id` in https://linkedin.com/company/my-linkedin-id)." }, "description": { "type": "string", "description": "Company description." }, "pictureUrl": { "type": "string", "description": "Company image URL." }, "type": { "type": "string", "description": "Company legal form (LLC, SAS, SARL, GmbH, ...)" }, "address": { "type": "string", "description": "Company headquarters address" }, "numberOfEmployees": { "type": "number", "description": "Number of employees (-1 when not known)." }, "headcountRange": { "type": "string", "description": "Declarative headcount range (e.g. 1-10 or 50-100)" }, "estimatedRevenuRange": { "type": "object", "properties": { "estimatedMaxRevenue": { "type": "object", "properties": { "amount": { "type": "number", "description": "Amount" }, "unit": { "type": "string", "description": "Amount unit (BILLION, MILLION, THOUSAND, ...)" }, "currency": { "type": "string", "description": "Amount currency (three letters)" } }, "required": [ "amount", "unit", "currency" ], "description": "Estimation of max revenue" }, "estimatedMinRevenue": { "type": "object", "properties": { "amount": { "type": "number", "description": "Amount" }, "unit": { "type": "string", "description": "Amount unit (BILLION, MILLION, THOUSAND, ...)" }, "currency": { "type": "string", "description": "Amount currency (three letters)" } }, "required": [ "amount", "unit", "currency" ], "description": "Estimation of min revenue" } }, "description": "Estimated revenue" }, "revenue": { "type": "object", "properties": { "amount": { "type": "number", "description": "Amount" }, "unit": { "type": "string", "description": "Amount unit (BILLION, MILLION, THOUSAND, ...)" }, "currency": { "type": "string", "description": "Amount currency (three letters)" } }, "required": [ "amount", "unit", "currency" ], "description": "When the revenue is known (because the company has to disclose it, for instance)" }, "employeeGrowth": { "type": "array", "items": { "type": "object", "properties": { "growth": { "type": "object", "properties": { "percentage": { "type": "number", "description": "Employee growth percentage" }, "timespan": { "type": "string", "description": "Time span (SIX_MONTHS, YEAR, TWO_YEAR, ...)" } }, "required": [ "percentage", "timespan" ], "description": "employee growth for a given timespan" } }, "required": [ "growth" ] }, "description": "Employee growth over the year" } }, "required": [ "_id", "name", "url", "urn", "specialties", "lid", "numberOfEmployees" ] }, "description": "An array containing the companies information" } }, "required": [ "success", "total", "leads" ] }, { "type": "object", "description": "Returned with HTTP 200 when the request body is invalid. See the `validationErrors` array for every problem.", "properties": { "success": { "type": "boolean", "const": false }, "validationErrors": { "type": "array", "items": { "type": "object", "properties": { "expected": { "description": "What the API expected (for example `string`)." }, "actual": { "description": "The value that was received." }, "type": { "type": "string", "description": "Validation error type, for example `required`." }, "field": { "type": "string", "description": "The field in error." }, "message": { "type": "string", "description": "Stable machine-readable code, for example `validation_required`." } } } } } } ] }, "examples": { "success": { "summary": "Response when no errors are sent", "value": { "success": true, "total": 845, "leads": [ { "name": "Harvard Graduate School of Education", "lid": "hgse", "urn": "urn:li:fs_salesCompany:1653", "url": "https://www.linkedin.com/company/hgse/", "description": "Education touches every aspect of human activity. At the Harvard Graduate School of Education (HGSE), we believe studying and improving the enterprise of education are central to the health and future of society.", "address": "Cambridge, Massachusetts, United States", "numberOfEmployees": 1134, "industry": "Higher Education", "website": "http://www.gse.harvard.edu", "specialties": [], "employeeGrowth": [], "_id": "sMMXT5MBIateb5xQKCCK" }, { "name": "Trammell Crow Company", "lid": "trammell-crow-company", "urn": "urn:li:fs_salesCompany:2320", "url": "https://www.linkedin.com/company/trammell-crow-company/", "description": "Trammell Crow Company (TCC) is a global commercial real estate developer and wholly-owned subsidiary of CBRE Group, Inc. (NYSE:CBRE), a Fortune 500 and S&P 500 company headquartered in Dallas. Founded in 1948, TCC has developed or acquired nearly 2,900 buildings valued at $75 billion and over 655 million square feet. As of September 30, 2024, TCC had $19 billion of projects in process and $13.4 billion in its pipeline. With 575 employees throughout the United States and Europe in 27 offices, the company serves users of and investors in office, industrial/logistics, healthcare, life science, data center and mixed-use projects, as well as multi-family residential through its operating subsidiary High Street Residential. For more information visit www.TrammellCrow.com.", "address": "Dallas, Texas, United States", "numberOfEmployees": 989, "industry": "Real Estate", "website": "http://www.trammellcrow.com", "specialties": [], "employeeGrowth": [], "_id": "-sMXT5MBIateb5xQeCIO" } ], "pagination": { "size": 2, "token": "xxxxxx" } } }, "validationError": { "summary": "Response when there are validation errors.", "value": { "validationErrors": [ { "expected": "object with props defined in the schema", "type": "objectStrict", "actual": { "x": 10 }, "field": "query.headcount", "message": "The object 'query.headcount' contains forbidden keys." } ], "success": false } } } } } }, "401": { "description": "Response when we could not authenticate you.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error name" }, "status": { "type": "number", "description": "HTTP error code" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message", "error", "status", "code" ] }, "examples": { "success": { "summary": "Response when we could not authenticate you.", "value": { "message": "Unauthorized access.", "error": "UnauthorizedAccessError", "status": 401, "code": "unauthorized_access_error" } } } } } }, "429": { "description": "Error received when rate limit is exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error name" }, "status": { "type": "number", "description": "HTTP error code" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message", "error", "status", "code" ] }, "examples": { "success": { "summary": "Error received when rate limit is exceeded", "value": { "message": "You have exceeded the max number of requests per minute.", "error": "RateLimitExceededError", "status": 429, "code": "rate_limit_exceeded_error" } } } } } } } } }, "/url-search/company": { "post": { "operationId": "findOneCompanyUrl", "summary": "Find one company URL", "tags": [ "Profiles & companies" ], "externalDocs": { "url": "https://api-doc.icypeas.com/reference/find-company-url", "description": "Documentation: Company URL finder: find a company's page URL" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyOrDomain": { "type": "string", "description": "It should contain either the company name or its domain name (or website)" } }, "required": [ "companyOrDomain" ] }, "examples": { "find-one-company-url-1": { "summary": "Find one company URL", "value": { "companyOrDomain": "nec technologies" } } } } } }, "responses": { "200": { "description": "Response when the company URL is found / Response when the company URL is not found / Response when there are validation errors.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "success": { "type": "boolean", "description": "true means that your search succeeded (no error was raised on our side)" }, "searchId": { "type": "string", "description": "The id of the search item (if you need to fetch the result later using the dedicated route)" }, "status": { "type": "string", "description": "FOUND because the company has been found" }, "result": { "type": "string", "description": "The company URL" } }, "required": [ "success", "searchId", "status", "result" ] }, { "type": "object", "properties": { "success": { "type": "boolean", "description": "true means that your search succeeded (no error was raised on our side)" }, "searchId": { "type": "string", "description": "The id of the search item (if you need to fetch the result later using the dedicated route)" }, "status": { "type": "string", "description": "NOT_FOUND because the company was not found" }, "result": { "type": "string", "description": "The field is an empty string" } }, "required": [ "success", "searchId", "status", "result" ] }, { "type": "object", "description": "Returned with HTTP 200 when the request body is invalid. See the `validationErrors` array for every problem.", "properties": { "success": { "type": "boolean", "const": false }, "validationErrors": { "type": "array", "items": { "type": "object", "properties": { "expected": { "description": "What the API expected (for example `string`)." }, "actual": { "description": "The value that was received." }, "type": { "type": "string", "description": "Validation error type, for example `required`." }, "field": { "type": "string", "description": "The field in error." }, "message": { "type": "string", "description": "Stable machine-readable code, for example `validation_required`." } } } } } } ] }, "examples": { "success": { "summary": "Response when the company URL is not found", "value": { "success": true, "searchId": "#YOUR_SEARCH_ID#", "status": "NOT_FOUND", "result": "" } }, "validationError": { "summary": "Response when there are validation errors.", "value": { "validationErrors": [ { "field": "companyOrDomain", "message": "validation_string_empty", "humanReadableMessage": "The string is empty", "actual": "" } ], "success": false } } } } } }, "401": { "description": "Response when we could not authenticate you.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error name" }, "status": { "type": "number", "description": "HTTP error code" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message", "error", "status", "code" ] }, "examples": { "success": { "summary": "Response when we could not authenticate you.", "value": { "message": "Unauthorized access.", "error": "UnauthorizedAccessError", "status": 401, "code": "unauthorized_access_error" } } } } } }, "429": { "description": "Error received when rate limit is exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error name" }, "status": { "type": "number", "description": "HTTP error code" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message", "error", "status", "code" ] }, "examples": { "success": { "summary": "Error received when rate limit is exceeded", "value": { "message": "You have exceeded the max number of requests per minute.", "error": "RateLimitExceededError", "status": 429, "code": "rate_limit_exceeded_error" } } } } } } } } }, "/url-search": { "post": { "operationId": "findUpTo50CompanyUrls", "summary": "Find up to 50 company URLs / Find up to 50 profile URLs", "tags": [ "Profiles & companies" ], "externalDocs": { "url": "https://api-doc.icypeas.com/reference/find-company-url", "description": "Documentation: Company URL finder: find a company's page URL" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "description": "The type of data Rule: should always be 'company'." }, "data": { "type": "array", "items": { "type": "object", "properties": { "companyOrDomain": { "type": "string", "description": "It should contains either the company name or its domain name (or website)" } }, "required": [ "companyOrDomain" ] }, "description": "An array containing the companies' information. Max number of companies per request is 50" } }, "required": [ "type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "The type of data Rule: should always be 'profile'." }, "data": { "type": "array", "items": { "type": "object", "properties": { "firstname": { "type": "string", "description": "First name of your prospect" }, "lastname": { "type": "string", "description": "Last name of your prospect" }, "companyOrDomain": { "type": "string", "description": "It should contain either the company name or its domain name (or website) Rule: Can be empty if jobTitle is given." }, "jobTitle": { "type": "string", "description": "It should contain the job title of your prospect Rule: Can be empty if companyOrDomain is given." } }, "required": [ "firstname", "lastname" ] }, "description": "An array containing the profiles' information. Max number of profiles per request is 50" } }, "required": [ "type", "data" ] } ] }, "examples": { "find-up-to-50-company-urls-1": { "summary": "Find up to 50 company URLs", "value": { "type": "company", "data": [ { "companyOrDomain": "nec technologies" }, { "companyOrDomain": "icypessaezeaze" } ] } }, "find-up-to-50-profile-urls-1": { "summary": "Find up to 50 profile URLs", "value": { "type": "profile", "data": [ { "firstname": "Marc", "lastname": "Lachabody", "companyOrDomain": "nec technologies" }, { "firstname": "Katrina", "lastname": "Larenkova", "companyOrDomain": "apple" } ] } } } } } }, "responses": { "200": { "description": "Response when your input does not contain any validation errors / Response when there are validation errors.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "success": { "type": "boolean", "description": "true means that your search succeeded (no error was raised on our side)" }, "data": { "type": "array", "items": { "type": "object", "properties": { "searchId": { "type": "string", "description": "The id of each search item (if you need to fetch the result later using the dedicated route)" }, "status": { "type": "string", "description": "FOUND when the company was found & NOT_FOUND when not" }, "result": { "type": "string", "description": "The company URL or an empty string is the company page is not found" } }, "required": [ "searchId", "status", "result" ] } } }, "required": [ "success", "data" ] }, { "type": "object", "description": "Returned with HTTP 200 when the request body is invalid. See the `validationErrors` array for every problem.", "properties": { "success": { "type": "boolean", "const": false }, "validationErrors": { "type": "array", "items": { "type": "object", "properties": { "expected": { "description": "What the API expected (for example `string`)." }, "actual": { "description": "The value that was received." }, "type": { "type": "string", "description": "Validation error type, for example `required`." }, "field": { "type": "string", "description": "The field in error." }, "message": { "type": "string", "description": "Stable machine-readable code, for example `validation_required`." } } } } } } ] }, "examples": { "success": { "summary": "Response when your input does not contain any validation errors", "value": { "success": true, "data": [ { "searchId": "#YOUR_SEARCH_ID_1#", "status": "FOUND", "result": "https://www.linkedin.com/in/nec-technologies" }, { "searchId": "#YOUR_SEARCH_ID_2#", "status": "NOT_FOUND", "result": "" } ] } }, "validationError": { "summary": "Response when there are validation errors.", "value": { "validationErrors": [ { "field": "url", "message": "wrong_linkedin_url", "humanReadableMessage": "All URLs in the data array should be a profile URL. Please check URLs at indices: 1", "type": "WrongLinkedinUrl", "expected": null, "actual": [ "https://www.linkedin.com/company/nec-technologies", "https://www.linkedin.com/xx/apple/" ] } ], "success": false } } } } } }, "401": { "description": "Response when we could not authenticate you.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error name" }, "status": { "type": "number", "description": "HTTP error code" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message", "error", "status", "code" ] }, "examples": { "success": { "summary": "Response when we could not authenticate you.", "value": { "message": "Unauthorized access.", "error": "UnauthorizedAccessError", "status": 401, "code": "unauthorized_access_error" } } } } } }, "429": { "description": "Error received when rate limit is exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error name" }, "status": { "type": "number", "description": "HTTP error code" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message", "error", "status", "code" ] }, "examples": { "success": { "summary": "Error received when rate limit is exceeded", "value": { "message": "You have exceeded the max number of requests per minute.", "error": "RateLimitExceededError", "status": 429, "code": "rate_limit_exceeded_error" } } } } } } } } }, "/find-people/count": { "post": { "operationId": "countMatchingPeopleFree", "summary": "Count matching people (free)", "tags": [ "Lead database" ], "externalDocs": { "url": "https://api-doc.icypeas.com/reference/find-people", "description": "Documentation: Find people: search the B2B lead database" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "object", "properties": {}, "description": "The query Rule: should be a valid query (see available fields above)." } }, "required": [ "query" ] } } } }, "responses": { "200": { "description": "Response when they are no errors / Response when there are validation errors.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "success": { "type": "boolean", "description": "true means that your search succeeded (no error was raised on our side)" }, "total": { "type": "number", "description": "The number of people" } }, "required": [ "success", "total" ] }, { "type": "object", "description": "Returned with HTTP 200 when the request body is invalid. See the `validationErrors` array for every problem.", "properties": { "success": { "type": "boolean", "const": false }, "validationErrors": { "type": "array", "items": { "type": "object", "properties": { "expected": { "description": "What the API expected (for example `string`)." }, "actual": { "description": "The value that was received." }, "type": { "type": "string", "description": "Validation error type, for example `required`." }, "field": { "type": "string", "description": "The field in error." }, "message": { "type": "string", "description": "Stable machine-readable code, for example `validation_required`." } } } } } } ] }, "examples": { "success": { "summary": "Response when they are no errors", "value": { "success": true, "total": 10 } }, "validationError": { "summary": "Response when there are validation errors.", "value": { "validationErrors": [ { "expected": "object with props defined in the schema", "type": "objectStrict", "actual": { "x": 10 }, "field": "query.headcount", "message": "The object 'query.headcount' contains forbidden keys." } ], "success": false } } } } } }, "401": { "description": "Response when we could not authenticate you.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error name" }, "status": { "type": "number", "description": "HTTP error code" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message", "error", "status", "code" ] }, "examples": { "success": { "summary": "Response when we could not authenticate you.", "value": { "message": "Unauthorized access.", "error": "UnauthorizedAccessError", "status": 401, "code": "unauthorized_access_error" } } } } } }, "429": { "description": "Error received when rate limit is exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error name" }, "status": { "type": "number", "description": "HTTP error code" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message", "error", "status", "code" ] }, "examples": { "success": { "summary": "Error received when rate limit is exceeded", "value": { "message": "You have exceeded the max number of requests per minute.", "error": "RateLimitExceededError", "status": 429, "code": "rate_limit_exceeded_error" } } } } } } } } }, "/find-people": { "post": { "operationId": "fetchMatchingPeople", "summary": "Fetch matching people", "tags": [ "Lead database" ], "externalDocs": { "url": "https://api-doc.icypeas.com/reference/find-people", "description": "Documentation: Find people: search the B2B lead database" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "object", "properties": {}, "description": "The query Rule: should be a valid query (see available fields above)." }, "pagination": { "type": "object", "properties": { "token": { "type": "string", "description": "The token returned with the previous page. Valid 15 minutes; each response returns a new token with a new 15-minute validity. Rule: should be a valid pagination token." }, "size": { "type": "number", "description": "The number of people returned per page Rule: should be a valid integer between 1 and 200.", "default": "100" } }, "required": [ "token" ], "description": "This is optional and used only if you want to retrieve more people than the first page. Rule: should be a valid pagination object." } }, "required": [ "query" ] } } } }, "responses": { "200": { "description": "Response when no errors are sent / Response when there are validation errors.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "success": { "type": "boolean", "description": "true means that your search succeeded (no error was raised on our side)" }, "total": { "type": "number", "description": "The number of people" }, "pagination": { "type": "object", "properties": { "token": { "type": "string", "description": "Token to request the next page. Valid 15 minutes from this response: request the next page before it expires." }, "size": { "type": "number", "description": "The number of people returned per page", "default": "100" } }, "required": [ "token" ], "description": "This is used if you want to retrieve more people than the first page." }, "leads": { "type": "array", "items": { "type": "object", "properties": { "firstname": { "type": "string", "description": "The firstname of the lead" }, "lastname": { "type": "string", "description": "The lastname of the lead" }, "headline": { "type": "string", "description": "A brief summary or description of the lead's professional identity or role" }, "description": { "type": "string", "description": "Detailed information about the lead's background, experience, and accomplishments" }, "profileUrl": { "type": "string", "description": "The URL to the lead's LinkedIn profile" }, "lastJobTitle": { "type": "string", "description": "The title of the lead's most recent job position" }, "lastJobDescription": { "type": "string", "description": "A more detailed description about his/her most recent position" }, "lastJobStartDate": { "type": "string", "description": "The start date of the lead's most recent job position" }, "address": { "type": "string", "description": "The geographical location or address associated with the lead" }, "lastCompanyName": { "type": "string", "description": "The name of the company where the lead was most recently employed" }, "lastCompanyUrn": { "type": "string", "description": "The unique identifier (URN) of the most recent company on LinkedIn" }, "lastCompanyUrl": { "type": "string", "description": "The URL to the LinkedIn page of the lead's most recent company" }, "lastCompanyWebsite": { "type": "string", "description": "The website address of the lead's most recent company" }, "lastCompanyDescription": { "type": "string", "description": "A brief description or overview of the lead's most recent company" }, "lastCompanySize": { "type": "number", "description": "The number of employees inside the lead's most recent company" }, "lastCompanyIndustry": { "type": "string", "description": "The industry in which the lead's most recent company operates" }, "lastCompanyAddress": { "type": "string", "description": "The geographical location or address of the lead's most recent company" } }, "required": [ "firstname", "lastname" ] }, "description": "An array containing the people information" } }, "required": [ "success", "total", "leads" ] }, { "type": "object", "description": "Returned with HTTP 200 when the request body is invalid. See the `validationErrors` array for every problem.", "properties": { "success": { "type": "boolean", "const": false }, "validationErrors": { "type": "array", "items": { "type": "object", "properties": { "expected": { "description": "What the API expected (for example `string`)." }, "actual": { "description": "The value that was received." }, "type": { "type": "string", "description": "Validation error type, for example `required`." }, "field": { "type": "string", "description": "The field in error." }, "message": { "type": "string", "description": "Stable machine-readable code, for example `validation_required`." } } } } } } ] }, "examples": { "success": { "summary": "Response when no errors are sent", "value": { "success": true, "total": 4, "leads": [ { "firstname": "Pierre-Baptiste", "lastname": "Landoin", "headline": "CEO @Icypeas | Love discussing lead generation, sales automation, marketing hacks and entrepreneurship", "description": "I have co-founded:\n- Icypeas (Email Finder & Verifier, www.icypeas.com)\n- NSW PRIM (Model mapping, www.nswprim.com)\n- Superpitch (Animated Videos, www.superpitch.fr)\n- FileVirtuelle (Welcome Kiosks, www.filevirtuelle.com)\n- Cerbair (Drone Detection, www.cerbair.com)\n- MySeat (Connected Objects, www.myseat.fr)\n\nIn total, over 50 jobs created and €6M in revenue in 2021.", "profileUrl": "https://www.linkedin.com/in/pierre-baptiste-landoin-icypeas", "lastJobTitle": "Chief Executive Officer", "lastJobDescription": "Icypeas is a SaaS to find and verify email addresses. \n\n- unparalleled email discovery rate\n- lowest bounce rate \n\nDiscover more on https://www.icypeas.com.", "lastJobStartDate": "10-2022", "address": "Paris, Ile-de-France, France", "lastCompanyName": "Icypeas", "lastCompanyUrn": "urn:li:fs_salesCompany:89667826", "lastCompanyUrl": "https://www.linkedin.com/company/icypeas/", "lastCompanyWebsite": "https://www.icypeas.com", "lastCompanyDescription": "", "lastCompanySize": 4, "lastCompanyIndustry": "Software Development", "lastCompanyAddress": "Paris, Île-de-France, France" }, { "firstname": "Corentin", "lastname": "Ribeyre", "headline": "CTO at Icypeas", "description": "", "profileUrl": "https://www.linkedin.com/in/corentin-ribeyre-30085a3b", "lastJobTitle": "Chief Technology Officer / Founder", "lastJobDescription": "", "lastJobStartDate": "10-2022", "address": "Paris, Ile-de-France, France", "lastCompanyName": "Icypeas", "lastCompanyUrn": "urn:li:fs_salesCompany:89667826", "lastCompanyUrl": "https://www.linkedin.com/company/icypeas/", "lastCompanyWebsite": "https://www.icypeas.com", "lastCompanyDescription": "", "lastCompanySize": 4, "lastCompanyIndustry": "Software Development", "lastCompanyAddress": "Paris, Île-de-France, France" } ], "pagination": { "size": 2, "token": "xxxxxx" } } }, "validationError": { "summary": "Response when there are validation errors.", "value": { "validationErrors": [ { "expected": "object with props defined in the schema", "type": "objectStrict", "actual": { "x": 10 }, "field": "query.currentJobTitle", "message": "The object 'query.headcount' contains forbidden keys." } ], "success": false } } } } } }, "401": { "description": "Response when we could not authenticate you.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error name" }, "status": { "type": "number", "description": "HTTP error code" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message", "error", "status", "code" ] }, "examples": { "success": { "summary": "Response when we could not authenticate you.", "value": { "message": "Unauthorized access.", "error": "UnauthorizedAccessError", "status": 401, "code": "unauthorized_access_error" } } } } } }, "429": { "description": "Error received when rate limit is exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error name" }, "status": { "type": "number", "description": "HTTP error code" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message", "error", "status", "code" ] }, "examples": { "success": { "summary": "Error received when rate limit is exceeded", "value": { "message": "You have exceeded the max number of requests per minute.", "error": "RateLimitExceededError", "status": 429, "code": "rate_limit_exceeded_error" } } } } } } } } }, "/url-search/profile": { "post": { "operationId": "findOneProfileUrl", "summary": "Find one profile URL", "tags": [ "Profiles & companies" ], "externalDocs": { "url": "https://api-doc.icypeas.com/reference/find-profile-url", "description": "Documentation: Profile URL finder: find a person's profile URL" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "firstname": { "type": "string", "description": "First name of your prospect" }, "lastname": { "type": "string", "description": "Last name of your prospect" }, "companyOrDomain": { "type": "string", "description": "It should contain either the company name or its domain name (or website) Rule: Can be empty if jobTitle is given." }, "jobTitle": { "type": "string", "description": "It should contain the job title of your prospect Rule: Can be empty if companyOrDomain is given." } }, "required": [ "firstname", "lastname" ] }, "examples": { "find-one-profile-url-1": { "summary": "Find one profile URL", "value": { "firstname": "Marc", "lastname": "Lachabody", "companyOrDomain": "nec technologies" } } } } } }, "responses": { "200": { "description": "Response when the URL is found / Response when the URL is not found / Response when there are validation errors.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "success": { "type": "boolean", "description": "true means that your search succeeded (no error was raised on our side)" }, "searchId": { "type": "string", "description": "The id of the search item (if you need to fetch the result later using the dedicated route)" }, "status": { "type": "string", "description": "FOUND because the profile has been found" }, "result": { "type": "string", "description": "The profile URL" } }, "required": [ "success", "searchId", "status", "result" ] }, { "type": "object", "properties": { "success": { "type": "boolean", "description": "true means that your search succeeded (no error was raised on our side)" }, "searchId": { "type": "string", "description": "The id of the search item (if you need to fetch the result later using the dedicated route)" }, "status": { "type": "string", "description": "NOT_FOUND because the profile was not found" }, "result": { "type": "string", "description": "The field is an empty string" } }, "required": [ "success", "searchId", "status", "result" ] }, { "type": "object", "description": "Returned with HTTP 200 when the request body is invalid. See the `validationErrors` array for every problem.", "properties": { "success": { "type": "boolean", "const": false }, "validationErrors": { "type": "array", "items": { "type": "object", "properties": { "expected": { "description": "What the API expected (for example `string`)." }, "actual": { "description": "The value that was received." }, "type": { "type": "string", "description": "Validation error type, for example `required`." }, "field": { "type": "string", "description": "The field in error." }, "message": { "type": "string", "description": "Stable machine-readable code, for example `validation_required`." } } } } } } ] }, "examples": { "success": { "summary": "Response when the URL is not found", "value": { "success": true, "searchId": "#YOUR_SEARCH_ID#", "status": "NOT_FOUND", "result": "" } }, "validationError": { "summary": "Response when there are validation errors.", "value": { "validationErrors": [ { "field": "companyOrDomain", "message": "validation_string_empty", "humanReadableMessage": "The string is empty", "actual": "" } ], "success": false } } } } } }, "401": { "description": "Response when we could not authenticate you.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error name" }, "status": { "type": "number", "description": "HTTP error code" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message", "error", "status", "code" ] }, "examples": { "success": { "summary": "Response when we could not authenticate you.", "value": { "message": "Unauthorized access.", "error": "UnauthorizedAccessError", "status": 401, "code": "unauthorized_access_error" } } } } } }, "429": { "description": "Error received when rate limit is exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error name" }, "status": { "type": "number", "description": "HTTP error code" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message", "error", "status", "code" ] }, "examples": { "success": { "summary": "Error received when rate limit is exceeded", "value": { "message": "You have exceeded the max number of requests per minute.", "error": "RateLimitExceededError", "status": 429, "code": "rate_limit_exceeded_error" } } } } } } } } }, "/bulk-single-searchs/read": { "post": { "operationId": "readResults", "summary": "Read results", "tags": [ "Results" ], "externalDocs": { "url": "https://api-doc.icypeas.com/reference/get-results", "description": "Documentation: Read search results" }, "description": "Get results from single or bulk searches", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "description": "Type of searches ('bulk' for bulk searches, 'single' for single searches) Rule: single or bulk." }, "id": { "type": "string", "description": "The _id of the item you want to fetch Rule: existing id." }, "file": { "type": "string", "description": "The file id for your bulk. Useful when you want to retrieve only the searches for a given bulk Rule: has to be a valid fileId." }, "limit": { "type": "number", "description": "Number of results to fetch Rule: default value is 10, max value is 100." }, "next": { "type": "boolean", "description": "If you want to paginate, use this field. true = next page | false = previous page" }, "sorts": { "type": "array", "items": { "type": "object", "properties": { "sort item": { "type": "number", "description": "Tuples of (number, string)" } }, "required": [ "sort item" ] }, "description": "Array used to paginate your files, it is this item you need to pass to your requests to fetch the next page" } } }, "examples": { "api-bulk-single-searchs-read": { "summary": "/api/bulk-single-searchs/read", "value": { "mode": "bulk", "limit": 50, "file": "#FILEID#" } } } } } }, "responses": { "200": { "description": "Response when your input is good. / Response when there are validation errors.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "success": { "type": "boolean", "description": "This field lets you know if your request was successful" }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the search ('__icypeas__individual' if it is a single search)." }, "user": { "type": "string", "description": "User ID of the user linked to this search." }, "file": { "type": "string", "description": "File id when it is a bulk search" }, "results": { "type": "object", "properties": { "firstname": { "type": "string", "description": "First name found during the search, if any." }, "lastname": { "type": "string", "description": "Last name found during the search, if any." }, "fullname": { "type": "string", "description": "Concatenation of the user's first and last names, if any." }, "emails": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address found during the search." }, "certainty": { "type": "string", "description": "How sure Icypeas is that this address exists: ultra_sure, very_sure, probable, undeliverable or not_found. See the Email certainty page." }, "mxProvider": { "type": "string", "description": "Who hosts the mailbox (google, microsoft, ovh…). See the MX providers page." }, "mxRecords": { "type": "array", "items": {}, "description": "Array of MX records. Those are strings" } }, "required": [ "email", "certainty", "mxRecords" ] }, "description": "Array of the found email addresses." }, "phones": { "type": "array", "items": {}, "description": "Currently empty." }, "saasServices": { "type": "array", "items": {}, "description": "Currently empty." } }, "required": [ "firstname", "lastname", "fullname", "emails", "phones", "saasServices" ], "description": "Object containing the results of your search." }, "order": { "type": "number", "description": "If in bulk search mode, it is the row of the file it was in." }, "status": { "type": "string", "description": "Status of this search." }, "system": { "type": "object", "properties": { "createdAt": { "type": "string", "description": "ISO String Date representing the creation date of the search." }, "modifiedAt": { "type": "string", "description": "ISO String Date representing the last modification date of the search." } }, "required": [ "createdAt", "modifiedAt" ], "description": "Information concerning the search." }, "userData": { "type": "object", "properties": { "webhookUrl": { "type": "string", "description": "Custom webhook URL that will be called for this search (the field is empty if no URL has been passed when running the single/bulk search)" }, "externalId": { "type": "string", "description": "Custom id provided by the user (the field is empty if not custom id was passed when running the single/bulk search)" } }, "required": [ "webhookUrl", "externalId" ], "description": "Custom data that were passed when running either the bulk search or the single search" }, "_id": { "type": "string", "description": "ID of the search." } }, "required": [ "name", "user", "results", "order", "status", "system", "_id" ] }, "description": "Array of results" }, "total": { "type": "number", "description": "Total number of results" }, "sorts": { "type": "array", "items": { "type": "object", "properties": { "sort item": { "type": "number", "description": "Tuples of (number, string)" } }, "required": [ "sort item" ] }, "description": "Array used to paginate your files, it is this item you need to pass to your requests to fetch the next page" } }, "required": [ "success", "items", "total" ] }, { "type": "object", "description": "Returned with HTTP 200 when the request body is invalid. See the `validationErrors` array for every problem.", "properties": { "success": { "type": "boolean", "const": false }, "validationErrors": { "type": "array", "items": { "type": "object", "properties": { "expected": { "description": "What the API expected (for example `string`)." }, "actual": { "description": "The value that was received." }, "type": { "type": "string", "description": "Validation error type, for example `required`." }, "field": { "type": "string", "description": "The field in error." }, "message": { "type": "string", "description": "Stable machine-readable code, for example `validation_required`." } } } } } } ] }, "examples": { "success": { "summary": "Response when your input is good.", "value": { "success": true, "items": [ { "name": "My cool search", "user": "#USERID#", "file": "#FILEID#", "results": { "firstname": "Example", "lastname": "Email", "fullname": "Example Email", "gender": "UNKNOWN", "emails": [ { "email": "example-email@icypeas.com", "certainty": "ultra_sure", "mxProvider": "google", "mxRecords": [ "google.com" ] } ], "phones": [] }, "order": 0, "status": "FOUND", "system": { "createdAt": "2023-01-01T13:49:49.630Z", "modifiedAt": "2023-01-01T13:49:49.630Z" }, "userData": { "externalId": "my-custom-id", "webhookUrl": "https://www.call-me-when-done.com/my-custom-id" }, "_id": "oSmI5YYBMa6Snk9TvjDA" } ], "total": 2534, "sorts": [ [ 1679388635082, "xxxx" ], [ 1679388543443, "yyyy" ] ] } }, "validationError": { "summary": "Response when there are validation errors.", "value": { "validationErrors": [ { "expected": "string", "type": "required", "field": "user", "message": "validation_required" } ], "success": false } } } } } }, "401": { "description": "Response when we could not authenticate you.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error name" }, "status": { "type": "number", "description": "HTTP error code" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message", "error", "status", "code" ] }, "examples": { "success": { "summary": "Response when we could not authenticate you.", "value": { "message": "Unauthorized access.", "error": "UnauthorizedAccessError", "status": 401, "code": "unauthorized_access_error" } } } } } }, "429": { "description": "Error received when rate limit is exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error name" }, "status": { "type": "number", "description": "HTTP error code" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message", "error", "status", "code" ] }, "examples": { "success": { "summary": "Error received when rate limit is exceeded", "value": { "message": "You have exceeded the max number of requests per minute.", "error": "RateLimitExceededError", "status": 429, "code": "rate_limit_exceeded_error" } } } } } } } } }, "/reverse-email-lookup": { "post": { "operationId": "lookUpOneEmail", "summary": "Look up one email", "tags": [ "Profiles & companies" ], "externalDocs": { "url": "https://api-doc.icypeas.com/reference/reverse-email-lookup", "description": "Documentation: Reverse email lookup: find the person behind an email" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "A professional email address " } }, "required": [ "email" ] }, "examples": { "look-up-one-email-1": { "summary": "Look up one email", "value": { "email": "pierre.landoin@icypeas.com" } } } } } }, "responses": { "200": { "description": "Response when your input is compliant and a profile URL has been found / Response when your input is compliant but the profile URL cannot be found / Response when there are validation errors", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "success": { "type": "boolean", "description": "true means that your search succeeded (no error was raised on our side)" }, "searchId": { "type": "string", "description": "The id of the search item (if you need to fetch the result later using the dedicated route)" }, "status": { "type": "string", "description": "FOUND because the profile URL was found" }, "result": { "type": "string", "description": "The profile URL" } }, "required": [ "success", "searchId", "status", "result" ] }, { "type": "object", "properties": { "success": { "type": "boolean", "description": "true means that your search succeeded (no error was raised on our side)" }, "searchId": { "type": "string", "description": "The id of the search item (if you need to fetch the result later using the dedicated route)" }, "status": { "type": "string", "description": "NOT_FOUND because nothing was found" }, "result": { "type": "string", "description": "An empty string, because nothing was found" } }, "required": [ "success", "searchId", "status", "result" ] }, { "type": "object", "description": "Returned with HTTP 200 when the request body is invalid. See the `validationErrors` array for every problem.", "properties": { "success": { "type": "boolean", "const": false }, "validationErrors": { "type": "array", "items": { "type": "object", "properties": { "expected": { "description": "What the API expected (for example `string`)." }, "actual": { "description": "The value that was received." }, "type": { "type": "string", "description": "Validation error type, for example `required`." }, "field": { "type": "string", "description": "The field in error." }, "message": { "type": "string", "description": "Stable machine-readable code, for example `validation_required`." } } } } } } ] }, "examples": { "success": { "summary": "Response when your input is compliant but the profile URL cannot be found", "value": { "success": true, "results": "", "searchId": "RUiDo5sBptEgZPBRAC8O", "status": "NOT_FOUND" } }, "validationError": { "summary": "Response when there are validation errors", "value": { "validationErrors": [ { "expected": "email", "type": "required", "field": "email", "message": "validation_required" } ], "success": false } } } } } }, "401": { "description": "Response when we could not authenticate you.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error name" }, "status": { "type": "number", "description": "HTTP error code" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message", "error", "status", "code" ] }, "examples": { "success": { "summary": "Response when we could not authenticate you.", "value": { "message": "Unauthorized access.", "error": "UnauthorizedAccessError", "status": 401, "code": "unauthorized_access_error" } } } } } }, "429": { "description": "Error received when rate limit is exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error name" }, "status": { "type": "number", "description": "HTTP error code" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message", "error", "status", "code" ] }, "examples": { "success": { "summary": "Error received when rate limit is exceeded", "value": { "message": "You have exceeded the max number of requests per minute.", "error": "RateLimitExceededError", "status": 429, "code": "rate_limit_exceeded_error" } } } } } } } } }, "/reverse-email-lookups": { "post": { "operationId": "lookUpTo50Emails", "summary": "Look up to 50 emails", "tags": [ "Profiles & companies" ], "externalDocs": { "url": "https://api-doc.icypeas.com/reference/reverse-email-lookup", "description": "Documentation: Reverse email lookup: find the person behind an email" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {}, "description": "An array of professional email addresses. Minimum of 2 addresses, maximum of 50 addresses Rule: should be valid email addresses." } }, "required": [ "data" ] }, "examples": { "look-up-to-50-emails-1": { "summary": "Look up to 50 emails", "value": { "data": [ "pierre.landoin@icypeas.com", "magnus@icypeas.com" ] } } } } } }, "responses": { "200": { "description": "Response when your input is compliant / Response when there are validation errors", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "success": { "type": "boolean", "description": "true means that your search succeeded (no error was raised on our side)" }, "data": { "type": "array", "items": { "type": "object", "properties": { "searchId": { "type": "string", "description": "The id of the search item (if you need to fetch the result later using the dedicated route)" }, "status": { "type": "string", "description": "FOUND if the profile URL was found. NOT_FOUND otherwise" }, "result": { "type": "string", "description": "The profile URL (if FOUND). An empty string otherwise" } }, "required": [ "searchId", "status", "result" ] } } }, "required": [ "success", "data" ] }, { "type": "object", "description": "Returned with HTTP 200 when the request body is invalid. See the `validationErrors` array for every problem.", "properties": { "success": { "type": "boolean", "const": false }, "validationErrors": { "type": "array", "items": { "type": "object", "properties": { "expected": { "description": "What the API expected (for example `string`)." }, "actual": { "description": "The value that was received." }, "type": { "type": "string", "description": "Validation error type, for example `required`." }, "field": { "type": "string", "description": "The field in error." }, "message": { "type": "string", "description": "Stable machine-readable code, for example `validation_required`." } } } } } } ] }, "examples": { "success": { "summary": "Response when your input is compliant", "value": { "success": true, "data": [ { "searchId": "RUiDo5sBptEgZPBRAC7O", "status": "FOUND", "result": "https://www.linkedin.com/in/pierre-baptiste-landoin-icypeas" }, { "searchId": "RDiDo5sBptEgZPBRAC81", "status": "NOT_FOUND", "result": "" } ] } }, "validationError": { "summary": "Response when there are validation errors", "value": { "validationErrors": [ { "expected": "email", "type": "required", "field": "email", "message": "validation_required" } ], "success": false } } } } } }, "401": { "description": "Response when we could not authenticate you.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error name" }, "status": { "type": "number", "description": "HTTP error code" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message", "error", "status", "code" ] }, "examples": { "success": { "summary": "Response when we could not authenticate you.", "value": { "message": "Unauthorized access.", "error": "UnauthorizedAccessError", "status": 401, "code": "unauthorized_access_error" } } } } } }, "429": { "description": "Error received when rate limit is exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error name" }, "status": { "type": "number", "description": "HTTP error code" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message", "error", "status", "code" ] }, "examples": { "success": { "summary": "Error received when rate limit is exceeded", "value": { "message": "You have exceeded the max number of requests per minute.", "error": "RateLimitExceededError", "status": 429, "code": "rate_limit_exceeded_error" } } } } } } } } }, "/scrape/company": { "get": { "operationId": "scrapeOneCompany", "summary": "Scrape one company", "tags": [ "Profiles & companies" ], "externalDocs": { "url": "https://api-doc.icypeas.com/reference/scrape-company", "description": "Documentation: Company scraper: get a company's data from its page URL" }, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "The company URL Rule: should be a correctly formatted company profile (e.g. https://www.linkedin.com/company/my-linkedin-id).", "schema": { "type": "string", "description": "The company URL Rule: should be a correctly formatted company profile (e.g. https://www.linkedin.com/company/my-linkedin-id)." } } ], "responses": { "200": { "description": "Response when the company is found / Response when the company is not found / Response when there are validation errors.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "success": { "type": "boolean", "description": "true means that your search succeeded (no error was raised on our side)" }, "searchId": { "type": "string", "description": "The id of the search item (if you need to fetch the result later using the dedicated route)" }, "status": { "type": "string", "description": "FOUND because the profile has been found" }, "result": { "type": "object", "properties": { "id": { "type": "string", "description": "Icypeas unique identifier." }, "name": { "type": "string", "description": "Company name" }, "url": { "type": "string", "description": "LinkedIn company URL." }, "urn": { "type": "string", "description": "LinkedIn company URN." }, "website": { "type": "string", "description": "Company website" }, "phone": { "type": "string", "description": "Main phone number given by the company (unnormalized, we keep what was given)" }, "slogan": { "type": "string", "description": "Company slogan" }, "industry": { "type": "string", "description": "Company industry" }, "foundedYear": { "type": "number", "description": "Company founded year (-1 when not known)" }, "specialties": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "Data value." } }, "required": [ "value" ] }, "description": "Company specialties" }, "lid": { "type": "string", "description": "LinkedIn ID (the `my-linkedin-id` in https://linkedin.com/company/my-linkedin-id)." }, "description": { "type": "string", "description": "Company description." }, "pictureUrl": { "type": "string", "description": "Company image URL." }, "type": { "type": "string", "description": "Company legal form (LLC, SAS, SARL, GmbH, ...)" }, "address": { "type": "object", "properties": { "streetAddress": { "type": "string", "description": "Street address." }, "addressLocality": { "type": "string", "description": "Address locality." }, "addressRegion": { "type": "string", "description": "Address region." }, "postalCode": { "type": "string", "description": "Postal code." }, "addressCountry": { "type": "string", "description": "Address country." }, "addressCountryCode": { "type": "string", "description": "Address country code (ISO Alpha 2 or UNK)." } }, "required": [ "streetAddress", "addressLocality", "addressRegion", "postalCode", "addressCountry", "addressCountryCode" ], "description": "Address information." }, "deleted": { "type": "boolean", "description": "Indicates if the company has been deleted." }, "numberOfEmployees": { "type": "number", "description": "Number of employees (-1 when not known)." }, "headcountRange": { "type": "string", "description": "Declarative headcount range (e.g. 1-10 or 50-100)" }, "estimatedRevenuRange": { "type": "object", "properties": { "estimatedMaxRevenue": { "type": "object", "properties": { "amount": { "type": "number", "description": "Amount" }, "unit": { "type": "string", "description": "Amount unit (BILLION, MILLION, THOUSAND, ...)" }, "currency": { "type": "string", "description": "Amount currency (three letters)" } }, "required": [ "amount", "unit", "currency" ], "description": "Estimation of max revenue" }, "estimatedMinRevenue": { "type": "object", "properties": { "amount": { "type": "number", "description": "Amount" }, "unit": { "type": "string", "description": "Amount unit (BILLION, MILLION, THOUSAND, ...)" }, "currency": { "type": "string", "description": "Amount currency (three letters)" } }, "required": [ "amount", "unit", "currency" ], "description": "Estimation of min revenue" } }, "description": "Estimated revenue" }, "revenue": { "type": "object", "properties": { "amount": { "type": "number", "description": "Amount" }, "unit": { "type": "string", "description": "Amount unit (BILLION, MILLION, THOUSAND, ...)" }, "currency": { "type": "string", "description": "Amount currency (three letters)" } }, "required": [ "amount", "unit", "currency" ], "description": "When the revenue is known (because the company has to disclose it, for instance)" }, "employeeGrowth": { "type": "array", "items": { "type": "object", "properties": { "growth": { "type": "object", "properties": { "percentage": { "type": "number", "description": "Employee growth percentage" }, "timespan": { "type": "string", "description": "Time span (SIX_MONTHS, YEAR, TWO_YEAR, ...)" } }, "required": [ "percentage", "timespan" ], "description": "employee growth for a given timespan" } }, "required": [ "growth" ] }, "description": "Employee growth over the year" } }, "required": [ "id", "name", "url", "urn", "specialties", "lid", "address", "numberOfEmployees" ], "description": "The company" } }, "required": [ "success", "searchId", "status", "result" ] }, { "type": "object", "properties": { "success": { "type": "boolean", "description": "true means that your search succeeded (no error was raised on our side)" }, "searchId": { "type": "string", "description": "The id of the search item (if you need to fetch the result later using the dedicated route)" }, "status": { "type": "string", "description": "NOT_FOUND because the company was not found" }, "result": { "type": "object", "properties": {}, "description": "The field is null" } }, "required": [ "success", "searchId", "status", "result" ] }, { "type": "object", "description": "Returned with HTTP 200 when the request body is invalid. See the `validationErrors` array for every problem.", "properties": { "success": { "type": "boolean", "const": false }, "validationErrors": { "type": "array", "items": { "type": "object", "properties": { "expected": { "description": "What the API expected (for example `string`)." }, "actual": { "description": "The value that was received." }, "type": { "type": "string", "description": "Validation error type, for example `required`." }, "field": { "type": "string", "description": "The field in error." }, "message": { "type": "string", "description": "Stable machine-readable code, for example `validation_required`." } } } } } } ] }, "examples": { "success": { "summary": "Response when the company is not found", "value": { "success": true, "searchId": "#YOUR_SEARCH_ID#", "status": "NOT_FOUND", "result": null } }, "validationError": { "summary": "Response when there are validation errors.", "value": { "validationErrors": [ { "field": "url", "message": "wrong_linkedin_url", "humanReadableMessage": "The URL should be a company URL", "type": "WrongLinkedinUrl", "expected": null, "actual": "https://linkedin.com/xaeaea/zzz" } ], "success": false } } } } } }, "401": { "description": "Response when we could not authenticate you.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error name" }, "status": { "type": "number", "description": "HTTP error code" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message", "error", "status", "code" ] }, "examples": { "success": { "summary": "Response when we could not authenticate you.", "value": { "message": "Unauthorized access.", "error": "UnauthorizedAccessError", "status": 401, "code": "unauthorized_access_error" } } } } } }, "429": { "description": "Error received when rate limit is exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error name" }, "status": { "type": "number", "description": "HTTP error code" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message", "error", "status", "code" ] }, "examples": { "success": { "summary": "Error received when rate limit is exceeded", "value": { "message": "You have exceeded the max number of requests per minute.", "error": "RateLimitExceededError", "status": 429, "code": "rate_limit_exceeded_error" } } } } } } } } }, "/scrape": { "post": { "operationId": "scrapeUpTo50Companies", "summary": "Scrape up to 50 companies / Scrape up to 50 profiles", "tags": [ "Profiles & companies" ], "externalDocs": { "url": "https://api-doc.icypeas.com/reference/scrape-company", "description": "Documentation: Company scraper: get a company's data from its page URL" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "description": "The type of data Rule: should always be 'company'." }, "data": { "type": "array", "items": {}, "description": "An array containing the company URLs to scrape. Max number of companies per request is 50 Rule: should be valid company URLs." } }, "required": [ "type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "The type of data Rule: should always be 'profile'." }, "data": { "type": "array", "items": {}, "description": "An array containing the profile URLs to scrape. Max number of profiles per request is 50 Rule: should be valid profile URLs." } }, "required": [ "type", "data" ] } ] }, "examples": { "scrape-up-to-50-companies-1": { "summary": "Scrape up to 50 companies", "value": { "type": "company", "data": [ "https://www.linkedin.com/company/nec-technologies", "https://www.linkedin.com/company/icypessaezeaze" ] } }, "scrape-up-to-50-profiles-1": { "summary": "Scrape up to 50 profiles", "value": { "type": "profile", "data": [ "https://www.linkedin.com/in/corentin-ribeyre-30085a3b", "https://www.linkedin.com/in/pierre-baptiste-landoin-icypes/" ] } } } } } }, "responses": { "200": { "description": "Response when your input does not contain any validation errors / Response when there are validation errors.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "success": { "type": "boolean", "description": "true means that your search succeeded (no error was raised on our side)" }, "data": { "type": "array", "items": { "type": "object", "properties": { "searchId": { "type": "string", "description": "The id of each search item (if you need to fetch the result later using the dedicated route)" }, "status": { "type": "string", "description": "FOUND when the company was found & NOT_FOUND when not" }, "result": { "type": "object", "properties": { "id": { "type": "string", "description": "Icypeas unique identifier." }, "name": { "type": "string", "description": "Company name" }, "url": { "type": "string", "description": "LinkedIn company URL." }, "urn": { "type": "string", "description": "LinkedIn company URN." }, "website": { "type": "string", "description": "Company website" }, "phone": { "type": "string", "description": "Main phone number given by the company (unnormalized, we keep what was given)" }, "slogan": { "type": "string", "description": "Company slogan" }, "industry": { "type": "string", "description": "Company industry" }, "foundedYear": { "type": "number", "description": "Company founded year (-1 when not known)" }, "specialties": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "Data value." } }, "required": [ "value" ] }, "description": "Company specialties" }, "lid": { "type": "string", "description": "LinkedIn ID (the `my-linkedin-id` in https://linkedin.com/company/my-linkedin-id)." }, "description": { "type": "string", "description": "Company description." }, "pictureUrl": { "type": "string", "description": "Company image URL." }, "type": { "type": "string", "description": "Company legal form (LLC, SAS, SARL, GmbH, ...)" }, "address": { "type": "object", "properties": { "streetAddress": { "type": "string", "description": "Street address." }, "addressLocality": { "type": "string", "description": "Address locality." }, "addressRegion": { "type": "string", "description": "Address region." }, "postalCode": { "type": "string", "description": "Postal code." }, "addressCountry": { "type": "string", "description": "Address country." }, "addressCountryCode": { "type": "string", "description": "Address country code (ISO Alpha 2 or UNK)." } }, "required": [ "streetAddress", "addressLocality", "addressRegion", "postalCode", "addressCountry", "addressCountryCode" ], "description": "Address information." }, "deleted": { "type": "boolean", "description": "Indicates if the company has been deleted." }, "numberOfEmployees": { "type": "number", "description": "Number of employees (-1 when not known)." }, "headcountRange": { "type": "string", "description": "Declarative headcount range (e.g. 1-10 or 50-100)" }, "estimatedRevenuRange": { "type": "object", "properties": { "estimatedMaxRevenue": { "type": "object", "properties": { "amount": { "type": "number", "description": "Amount" }, "unit": { "type": "string", "description": "Amount unit (BILLION, MILLION, THOUSAND, ...)" }, "currency": { "type": "string", "description": "Amount currency (three letters)" } }, "required": [ "amount", "unit", "currency" ], "description": "Estimation of max revenue" }, "estimatedMinRevenue": { "type": "object", "properties": { "amount": { "type": "number", "description": "Amount" }, "unit": { "type": "string", "description": "Amount unit (BILLION, MILLION, THOUSAND, ...)" }, "currency": { "type": "string", "description": "Amount currency (three letters)" } }, "required": [ "amount", "unit", "currency" ], "description": "Estimation of min revenue" } }, "description": "Estimated revenue" }, "revenue": { "type": "object", "properties": { "amount": { "type": "number", "description": "Amount" }, "unit": { "type": "string", "description": "Amount unit (BILLION, MILLION, THOUSAND, ...)" }, "currency": { "type": "string", "description": "Amount currency (three letters)" } }, "required": [ "amount", "unit", "currency" ], "description": "When the revenue is known (because the company has to disclose it, for instance)" }, "employeeGrowth": { "type": "array", "items": { "type": "object", "properties": { "growth": { "type": "object", "properties": { "percentage": { "type": "number", "description": "Employee growth percentage" }, "timespan": { "type": "string", "description": "Time span (SIX_MONTHS, YEAR, TWO_YEAR, ...)" } }, "required": [ "percentage", "timespan" ], "description": "employee growth for a given timespan" } }, "required": [ "growth" ] }, "description": "Employee growth over the year" } }, "required": [ "id", "name", "url", "urn", "specialties", "lid", "address", "numberOfEmployees" ], "description": "The company or null if no company was found" } }, "required": [ "searchId", "status", "result" ] } } }, "required": [ "success", "data" ] }, { "type": "object", "description": "Returned with HTTP 200 when the request body is invalid. See the `validationErrors` array for every problem.", "properties": { "success": { "type": "boolean", "const": false }, "validationErrors": { "type": "array", "items": { "type": "object", "properties": { "expected": { "description": "What the API expected (for example `string`)." }, "actual": { "description": "The value that was received." }, "type": { "type": "string", "description": "Validation error type, for example `required`." }, "field": { "type": "string", "description": "The field in error." }, "message": { "type": "string", "description": "Stable machine-readable code, for example `validation_required`." } } } } } } ] }, "examples": { "success": { "summary": "Response when your input does not contain any validation errors", "value": { "success": true, "data": [ { "searchId": "#YOUR_SEARCH_ID_1#", "status": "FOUND", "result": { "name": "NEC Technologies", "lid": "nec-technologies", "url": "https://www.linkedin.com/company/nec-technologies/", "description": "NEC Technologies", "urn": "urn:li:fs_salesCompany:1693", "address": { "streetAddress": "", "addressLocality": "Greater Tokyo Area", "addressRegion": "", "postalCode": "", "addressCountry": "Japan", "addressCountryCode": "JP" }, "headcountRange": "50-100", "phone": "+33 3 83 23 34 50", "numberOfEmployees": 62, "industry": "Computer Hardware Manufacturing", "website": "https://www.nec.com/", "specialties": [], "type": "Public Company", "deleted": false, "foundedYear": "1899", "pictureUrl": "https://icypeas-li-profile-pictures-production.s3.sbg.io.cloud.ovh.net/nec-technologies-8e6dd020f4614db796efc654ecb348fadcad0ed0f0674e71868bdaf129960a64", "estimatedRevenuRange": { "estimatedMaxRevenue": { "amount": 1000, "unit": "BILLION", "currency": "USD" }, "estimatedMinRevenue": { "amount": 1, "unit": "BILLION", "currency": "USD" } }, "employeeGrowth": [ { "percentage": 16, "timespan": "SIX_MONTHS" }, { "percentage": 40, "timespan": "YEAR" }, { "percentage": 40, "timespan": "TWO_YEAR" } ] } }, { "searchId": "#YOUR_SEARCH_ID_2#", "status": "NOT_FOUND", "result": null } ] } }, "validationError": { "summary": "Response when there are validation errors.", "value": { "validationErrors": [ { "field": "url", "message": "wrong_linkedin_url", "humanReadableMessage": "All URLs in the data array should be a profile URL. Please check URLs at indices: 1", "type": "WrongLinkedinUrl", "expected": null, "actual": [ "https://www.linkedin.com/company/nec-technologies", "https://www.linkedin.com/xx/apple/" ] } ], "success": false } } } } } }, "401": { "description": "Response when we could not authenticate you.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error name" }, "status": { "type": "number", "description": "HTTP error code" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message", "error", "status", "code" ] }, "examples": { "success": { "summary": "Response when we could not authenticate you.", "value": { "message": "Unauthorized access.", "error": "UnauthorizedAccessError", "status": 401, "code": "unauthorized_access_error" } } } } } }, "429": { "description": "Error received when rate limit is exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error name" }, "status": { "type": "number", "description": "HTTP error code" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message", "error", "status", "code" ] }, "examples": { "success": { "summary": "Error received when rate limit is exceeded", "value": { "message": "You have exceeded the max number of requests per minute.", "error": "RateLimitExceededError", "status": 429, "code": "rate_limit_exceeded_error" } } } } } } } } }, "/scrape/profile": { "get": { "operationId": "scrapeOneProfile", "summary": "Scrape one profile", "tags": [ "Profiles & companies" ], "externalDocs": { "url": "https://api-doc.icypeas.com/reference/scrape-profile", "description": "Documentation: Profile scraper: get a person's data from a profile URL" }, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "The profile URL Rule: should be a correctly formatted user profile (e.g. https://www.linkedin.com/in/my-linkedin-id).", "schema": { "type": "string", "description": "The profile URL Rule: should be a correctly formatted user profile (e.g. https://www.linkedin.com/in/my-linkedin-id)." } } ], "responses": { "200": { "description": "Response when the profile is found / Response when the profile is not found / Response when there are validation errors.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "success": { "type": "boolean", "description": "true means that your search succeeded (no error was raised on our side)" }, "searchId": { "type": "string", "description": "The id of the search item (if you need to fetch the result later using the dedicated route)" }, "status": { "type": "string", "description": "FOUND because the profile has been found" }, "result": { "type": "object", "properties": { "id": { "type": "string", "description": "Icypeas unique identifier." }, "firstname": { "type": "string", "description": "First name." }, "lastname": { "type": "string", "description": "Last name." }, "numOfConnections": { "type": "number", "description": "Number of connections." }, "headline": { "type": "string", "description": "Profile headline." }, "url": { "type": "string", "description": "Profile URL." }, "ContactInfo": { "type": "object", "properties": { "phoneNumber": { "type": "string", "description": "Phone number." }, "linkedinEmail": { "type": "string", "description": "Email address." } }, "required": [ "phoneNumber", "linkedinEmail" ], "description": "Contact information." }, "skills": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "Data value." } }, "required": [ "value" ] }, "description": "Skills." }, "languages": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "Data value." }, "norm": { "type": "string", "description": "Data normalized (country code, language code, etc.)." } }, "required": [ "value", "norm" ] }, "description": "Languages." }, "lid": { "type": "string", "description": "LinkedIn ID (the `my-linkedin-id` in https://linkedin.com/in/my-linkedin-id)." }, "linkedinEmail": { "type": "string", "description": "Email address." }, "description": { "type": "string", "description": "Profile description." }, "address": { "type": "object", "properties": { "streetAddress": { "type": "string", "description": "Street address." }, "addressLocality": { "type": "string", "description": "Address locality." }, "addressRegion": { "type": "string", "description": "Address region." }, "postalCode": { "type": "string", "description": "Postal code." }, "addressCountry": { "type": "string", "description": "Address country." }, "addressCountryCode": { "type": "string", "description": "Address country code (ISO Alpha 2 or UNK)." } }, "required": [ "streetAddress", "addressLocality", "addressRegion", "postalCode", "addressCountry", "addressCountryCode" ], "description": "Address information." }, "educations": { "type": "array", "items": { "type": "object", "properties": { "fieldsOfStudy": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "Data value." } }, "required": [ "value" ] }, "description": "Fields of study." }, "urn": { "type": "string", "description": "URN of the school" }, "name": { "type": "string", "description": "School name." }, "degree": { "type": "string", "description": "Degree earned." }, "startDate": { "type": "string", "description": "Start date (ISO 8601 format)." }, "endDate": { "type": "string", "description": "End date (ISO 8601 format)." }, "schoolInformation": { "type": "string", "description": "Additional school information. (if the education is still in progress this will be 0)" } }, "required": [ "fieldsOfStudy", "urn", "name", "degree", "startDate", "endDate", "schoolInformation" ] }, "description": "Education history." }, "worksFor": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Organization name." }, "location": { "type": "string", "description": "Organization location." }, "lid": { "type": "string", "description": "LinkedIn ID of the company." }, "urn": { "type": "string", "description": "URN of the organization entry." }, "startDate": { "type": "string", "description": "Start date (ISO 8601 format)." }, "endDate": { "type": "string", "description": "End date (ISO 8601 format). If the " }, "description": { "type": "string", "description": "Job description." }, "jobTitle": { "type": "string", "description": "Job title." } }, "required": [ "name", "location", "lid", "urn", "startDate", "endDate", "description", "jobTitle" ] }, "description": "Work experience." }, "alumniOf": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Organization name." }, "location": { "type": "string", "description": "Organization location." }, "lid": { "type": "string", "description": "LinkedIn ID of the company." }, "urn": { "type": "string", "description": "URN of the organization entry." }, "startDate": { "type": "string", "description": "Start date (ISO 8601 format)." }, "endDate": { "type": "string", "description": "End date (ISO 8601 format). If the " }, "description": { "type": "string", "description": "Job description." }, "jobTitle": { "type": "string", "description": "Job title." } }, "required": [ "name", "location", "lid", "urn", "startDate", "endDate", "description", "jobTitle" ] }, "description": "Alumni of organizations." }, "volunteeringExperiences": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Organization name." }, "location": { "type": "string", "description": "Organization location." }, "lid": { "type": "string", "description": "LinkedIn ID of the company." }, "urn": { "type": "string", "description": "URN of the organization entry." }, "startDate": { "type": "string", "description": "Start date (ISO 8601 format)." }, "endDate": { "type": "string", "description": "End date (ISO 8601 format). If the " }, "description": { "type": "string", "description": "Job description." }, "jobTitle": { "type": "string", "description": "Job title." } }, "required": [ "name", "location", "lid", "urn", "startDate", "endDate", "description", "jobTitle" ] }, "description": "Volunteering experiences." }, "openProfile": { "type": "boolean", "description": "Indicates if the profile is open to connections." }, "deleted": { "type": "boolean", "description": "Indicates if the profile has been deleted." } }, "required": [ "id", "firstname", "lastname", "numOfConnections", "url", "skills", "languages", "lid", "address", "educations", "worksFor", "alumniOf", "volunteeringExperiences" ], "description": "The profile" } }, "required": [ "success", "searchId", "status", "result" ] }, { "type": "object", "properties": { "success": { "type": "boolean", "description": "true means that your search succeeded (no error was raised on our side)" }, "searchId": { "type": "string", "description": "The id of the search item (if you need to fetch the result later using the dedicated route)" }, "status": { "type": "string", "description": "NOT_FOUND because the profile was not found" }, "result": { "type": "object", "properties": {}, "description": "The field is null" } }, "required": [ "success", "searchId", "status", "result" ] }, { "type": "object", "description": "Returned with HTTP 200 when the request body is invalid. See the `validationErrors` array for every problem.", "properties": { "success": { "type": "boolean", "const": false }, "validationErrors": { "type": "array", "items": { "type": "object", "properties": { "expected": { "description": "What the API expected (for example `string`)." }, "actual": { "description": "The value that was received." }, "type": { "type": "string", "description": "Validation error type, for example `required`." }, "field": { "type": "string", "description": "The field in error." }, "message": { "type": "string", "description": "Stable machine-readable code, for example `validation_required`." } } } } } } ] }, "examples": { "success": { "summary": "Response when the profile is not found", "value": { "success": true, "searchId": "#YOUR_SEARCH_ID#", "status": "NOT_FOUND", "result": null } }, "validationError": { "summary": "Response when there are validation errors.", "value": { "validationErrors": [ { "field": "url", "message": "wrong_linkedin_url", "humanReadableMessage": "The URL should be a user profile URL", "type": "WrongLinkedinUrl", "expected": null, "actual": "https://linkedin.com/xxx/martin-alejandro-espino-huaman-003a39206" } ], "success": false } } } } } }, "401": { "description": "Response when we could not authenticate you.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error name" }, "status": { "type": "number", "description": "HTTP error code" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message", "error", "status", "code" ] }, "examples": { "success": { "summary": "Response when we could not authenticate you.", "value": { "message": "Unauthorized access.", "error": "UnauthorizedAccessError", "status": 401, "code": "unauthorized_access_error" } } } } } }, "429": { "description": "Error received when rate limit is exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error name" }, "status": { "type": "number", "description": "HTTP error code" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message", "error", "status", "code" ] }, "examples": { "success": { "summary": "Error received when rate limit is exceeded", "value": { "message": "You have exceeded the max number of requests per minute.", "error": "RateLimitExceededError", "status": 429, "code": "rate_limit_exceeded_error" } } } } } } } } }, "/a/actions/subscription-information": { "post": { "operationId": "subscriptionCredits", "summary": "Subscription & credits", "tags": [ "Account" ], "externalDocs": { "url": "https://api-doc.icypeas.com/reference/subscription", "description": "Documentation: Subscription and remaining credits" }, "description": "Retrieve all the informations about your subscription and your credits.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The email of the user you want to retrieve the subscription. Rule: has to be an email." } }, "required": [ "email" ] }, "examples": { "subscription-credits-1": { "summary": "Subscription & credits", "value": { "email": "example@icypeas.com" } } } } } }, "responses": { "200": { "description": "Response when your input is good. / Response when there are validation errors", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "userId": { "type": "string", "description": "Icypeas user ID" }, "customerId": { "type": "string", "description": "Stripe user ID" }, "status": { "type": "string", "description": "Status of the user's payment" }, "credits": { "type": "number", "description": "Number of credits" }, "plan": { "type": "string", "description": "Name of the user's plan" }, "priceId": { "type": "string", "description": "ID of the price the user subscribed to" }, "lastInvoiceUrl": { "type": "string", "description": "URL for the user's last invoice" }, "checkoutSession": { "type": "string", "description": "Stripe checkout session" }, "currency": { "type": "string", "description": "Chosen currency of the user. It is an empty string is the user has never had a plan" }, "quotas": { "type": "object", "properties": { "daily": { "type": "number", "description": "Deprecated: Not used anymore. The value is still returned for backward compatibility but has no effect: ignore it. Daily quota that was used by the SalesNav extractor.", "deprecated": true } }, "required": [ "daily" ], "description": "Quotas available in Icypeas" } }, "required": [ "userId", "customerId", "status", "credits", "plan", "priceId", "lastInvoiceUrl", "checkoutSession", "currency", "quotas" ] }, { "type": "object", "description": "Returned with HTTP 200 when the request body is invalid. See the `validationErrors` array for every problem.", "properties": { "success": { "type": "boolean", "const": false }, "validationErrors": { "type": "array", "items": { "type": "object", "properties": { "expected": { "description": "What the API expected (for example `string`)." }, "actual": { "description": "The value that was received." }, "type": { "type": "string", "description": "Validation error type, for example `required`." }, "field": { "type": "string", "description": "The field in error." }, "message": { "type": "string", "description": "Stable machine-readable code, for example `validation_required`." } } } } } } ] }, "examples": { "success": { "summary": "Response when your input is good.", "value": { "userId": "ax782432ezeze89087", "customerId": "cus_NUigN0lSe4hOh9", "currency": "eur", "checkoutSession": "https://checkout.stripe.com/c/pay/cs_test_a1ekmO20jcbyBsDsNQjI5UUuM9VK4YIPgswGG9h7K6EQI9N7GENBcocA0z#fidkdWxOYHwnPyd1blpxYHZxWmNzZFBIfW5tfHJ1SE1VTE9cdEFDNWgycTU1R3BHM2tMPEQnKSdjd2poVmB3c2B3Jz9xd3BgKSdpZHxqcHFRfHVgJz8ndmxrYmlgWmxxYGgnKSdga2RnaWBVaWRmYG1qaWFgd3YnP3F3cGB4JSUl", "lastInvoiceUrl": "", "priceId": "price_1JPMUiIEPTjHbN3mQjFJqD46", "plan": "Basic Plan", "status": "paid", "credits": 24, "quotas": { "daily": 1000 } } }, "validationError": { "summary": "Response when there are validation errors", "value": { "validationErrors": [ { "expected": "email", "type": "stringEmpty", "actual": "", "field": "email", "message": "validation_string_empty" } ], "success": false } } } } } }, "401": { "description": "Response when we could not authenticate you.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error name" }, "status": { "type": "number", "description": "HTTP error code" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message", "error", "status", "code" ] }, "examples": { "success": { "summary": "Response when we could not authenticate you.", "value": { "message": "Unauthorized access.", "error": "UnauthorizedAccessError", "status": 401, "code": "unauthorized_access_error" } } } } } }, "429": { "description": "Error received when rate limit is exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error name" }, "status": { "type": "number", "description": "HTTP error code" }, "code": { "type": "string", "description": "Error code" } }, "required": [ "message", "error", "status", "code" ] }, "examples": { "success": { "summary": "Error received when rate limit is exceeded", "value": { "message": "You have exceeded the max number of requests per minute.", "error": "RateLimitExceededError", "status": 429, "code": "rate_limit_exceeded_error" } } } } } } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Your Icypeas API key, sent as is (no Bearer prefix)." } } } }