--- title: "Retrieve Contacts" method: GET path: "/v1/contacts" tags: ["Contacts", "v1"] --- # Retrieve Contacts `GET /v1/contacts` Retrieve a list of contacts based on the provided IDs. Credit Note: Each contact will contain its full deep data and it will consume 1 credit, unless the contact has already been accessed within the last 12 months. :::info Requires the `contacts:read` OAuth2 scope. ::: ## Query parameters - `ids` string, required - `account_id` string, required - `include` 'company' | 'lists' | 'buyer_personas' | 'crm_connections' | 'crm_connections.crm_record' | 'crm_connections.crm_record.crm_owner' | 'crm_suggestions' | 'crm_suggestions.crm_record' | 'crm_suggestions.crm_record.crm_owner' ## Response `200` Returns the contact details for the specified IDs. If `include=company` is supplied, the responses include the company details. If no contact is found for a certain ID, the `data` field will not contain an entry for that ID. - object - `data` ContactV1[], required - `type` 'contact', required — The type of the object - `id` string, required — The Leadfeeder contact ID. - `attributes` object, required - `address` object, required — Information about the contact's place of work based on sources like LinkedIn.com. - `city` string, nullable — The city name. - `country_code` string, nullable — This field indicates the country supported for Leadfeeder operations and requires a two letter country code according to ISO 3166 Alpha-2 (see [https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes)). - `country` string, nullable — The country name. - `region` string, nullable — The name of the region in native language." - `region_code` string, nullable — The code for the region. For European companies the NUTS1-3 schema is used. For companies outside of Europe values that comply with ISO 3166-2 with underscores are returned. - `affiliation` 'employee' | 'group_employee' | 'related', nullable, required — Determines how the contact is related to the company. - `custom_fields` object, required — A dictionary of custom field values, indexed by their unique field IDs. - `departments` string[], required — The departments the contact works in within the company. - `emails` object[], required — The contact's e-mail addresses. - `address` string, required — A standard e-mail address. - `source` string, nullable, required — The identifier of the source of data. - `first_name` string, nullable, required — The contact's first name. - `gender` 'male' | 'female' | 'other' | 'null', nullable, required — The contact's gender. - `hierarchy_level` 'employees' | 'top_management' | 'middle_management' | 'unknown_hierarchy' | 'null', nullable, required — The hierarchy level the contact has in the company. - `last_name` string, nullable, required — The contact's surname. - `phones` object[], required — The contact's direct phone numbers within the company. - `number` string, required — E.164 representation of a phone number. - `type` 'landline' | 'mobile' | 'fax', required — The type of phone number. - `blacklisted` boolean, nullable, required — Whether the company is not allowed to be contacted because it's part of a register like https://www.tpsonline.org.uk/pages/what_is_tps in the UK. When null, it means the blacklisted status is unknown. - `source` string, nullable, required — The identifier of the source of data. - `position` object, nullable, required — Information about the contact's position within the company. - `title` string, nullable — The contact's job title. - `language_code` string, nullable — A two digit language code indicating the language of the original job title according to ISO 639-1 (see https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) - `public_sources` object[], required - `type` 'homepage' | 'web' | 'register' — The type of the source. - `url` string — The URL to the website page for the source. - `social_media_profiles` object, required — List of social media pages. - `linkedin` object[] - `url` string - `source` string, nullable — The identifier of the source of data. - `instagram` object[] - `url` string - `source` string, nullable — The identifier of the source of data. - `facebook` object[] - `url` string - `source` string, nullable — The identifier of the source of data. - `twitter` object[] - `url` string - `source` string, nullable — The identifier of the source of data. - `youtube` object[] - `url` string - `source` string, nullable — The identifier of the source of data. - `pinterest` object[] - `url` string - `source` string, nullable — The identifier of the source of data. - `xing` object[] - `url` string - `source` string, nullable — The identifier of the source of data. - `title` string, nullable, required — The contact's title - `relationships` object, required - `company` union, required — The company the contact is associated with. By default this field only contains the `id` and `type` fields, but you can load all company attributes by passing the `include=company` url parameter. - object - `id` string, required — The Leadfeeder company ID. - `type` 'company', required - CompanyV1 - `type` 'company', required — The type of the object - `id` string, required — The Leadfeeder company ID. - `attributes` object, required - `address` object, required - … - `alternative_names` string[], required — An array of alternate / previous spellings of the company name. - `alternative_urls` string[], required — A set of alternative URLs related to the company. - `custom_fields` object, required — A dictionary of custom field values, indexed by their unique field IDs. - `description` string, nullable, required — A text containing information about the company (native language) - `earnings` object, nullable, required - … - `emails` object[], required — Email address(es) for the company (eg. info@, service@ or support@). - … - `employee_count` integer, nullable, required — The currently known headcount for this company. - `employee_range` '1-10' | '11-100' | '101-500' | '501-1.000' | '1.001-5.000' | '5.001-10.000' | '10.000+' | 'null', nullable, required — A range indicator of the approximate headcount for this company. - `founded_year` integer, nullable, required — A number representing the year when the company was founded. - `industries` object, required — A list of the company's industries. - … - `keywords` string[], required — An array of keywords about the company and its products that have been extracted from the website. They will be returned in your user's language. - `legal_form` string, nullable, required — The company's legal form (i.e. GmbH, SARL or Limited). - `logo_url` string, uri, nullable, required — The URL of the company's logo. - `meta` object, required - … - `name` string, required — The legal name of the company - `net_worth` object, nullable, required - … - `orientation` string[], required — The target audience(s) of the company. The value 'B2B' indicates that the company is primarily focused on business customers, while 'B2C' indicates a focus on individual consumers. The value 'OTHER' means it’s a public (likely non-commercial) service or institution. - `phones` object[], required — The central phone number(s) of the company. - … - `previous_ids` string[], required — A list of former ids that the company was known by in the past. The ID may have changed for example due to a merger with another company. The list is empty if there are no previous IDs. - `register` object, required - … - `revenue` object, nullable, required - … - `role` 'single_entity' | 'group' | 'group_member' | 'null', nullable, required — This field indicates the role of the company within its group structure. - `social_media_profiles` object, required — List of social media pages. - … - `url` string, nullable, required — The URL of the company website. - `vat_id` string, nullable, required — The company's VAT ID (tax ID). - `web_engagement` object, required — Web engagement data for a company. - … - `intent` object, required - … - `relationships` object, required - `group_company` union, required — The group company head. The field may be null if the company is a single entity. By default this field only contains the `id` and `type` fields, but you can load all company attributes by passing the `include=group_company` url parameter. - … - `tags` TagV1[] — Tags assigned to the company. By default this field is not displayed, but you can load it by passing the `include=tags` url parameter. - … - `lists` ListV1[] — Lists that include this company. By default this field is not displayed, but you can load it by passing the `include=lists` url parameter. - … - `web_visits` WebVisitV1[] — Web visits associated with the company. It returns first 20 visits from last 7 days. By default this field is not displayed, but you can load it by passing the `include=web_visits` url parameter. - … - `crm_connections` CRMConnectionV1[] — CRM connections associated with the company. By default this field is not displayed, but you can load it by passing the `include=crm_connections` url parameter. - … - `crm_suggestions` CRMSuggestionV1[] — CRM suggestions associated with the company. By default this field is not displayed, but you can load it by passing the `include=crm_suggestions` url parameter. - … - `crm_group_connections` CRMGroupConnectionV1[] — CRM group connections associated with the company. By default this field is not displayed, but you can load it by passing the `include=crm_group_connections` url parameter. - … - `icps` ICPV1[] — Ideal Customer Profiles (ICPs) defined in the account that this company matches. By default this field is not displayed, but you can load it by passing the `include=icps` url parameter. - … - `lists` ListV1[] — Lists that include this contact. By default this field is not displayed, but you can load it by passing the `include=lists` url parameter. - `type` 'list', required — The type of the object - `id` string, required — The unique identifier for the list - `attributes` object, required - `name` string, required — The human-readable name of the List - `scope` 'company' | 'contact', required — The scope type of the list - `created_at` string, date-time, required — Date and time when the list was created - `updated_at` string, date-time — Date and time when the list was updated - `relationships` object, required - `created_by` object, required - `id` string, required — The Leadfeeder user ID. - `type` string, required - `buyer_personas` BuyerPersonaV1[] — Buyer personas defined in the account that this contact matches. By default this field is not displayed, but you can load it by passing the `include=buyer_personas` url parameter. - `type` string, required — The type of the object - `id` string, required — The unique identifier for the buyer persona - `attributes` object, required - `name` string, required — The human-readable name of the buyer persona - `created_at` string, date-time, required — Date and time when the buyer persona was created - `filters` object, required — Filter criteria that define this buyer persona, grouped by filter category. Categories with no configured criteria are omitted. The object is empty when the buyer persona has no filters configured. - `department` object[] — Department filters. - … - `job_title` object[] — Job title keyword filters. - … - `location` object[] — Location filters. - … - `seniority` object[] — Seniority filters. - … - `meta` object, required - `credits` object, required - `charged` number, required — How many credits were consumed for this request. - `request_id` string, required — A unique identifier assigned to each API request for end-to-end traceability. ## Other responses - `400` — Invalid mandatory fields - `401` — Unauthorized. The request was rejected because the credentials are missing, invalid, expired, or have been revoked. The client must re-authenticate before retrying. Clients can differentiate via the `code` value of the first item in `errors`. - `403` — Forbidden. The credentials are valid but the caller is not authorized to perform the request — typically because the user lacks the required permission, the OAuth scope is insufficient, the subscription plan does not include the required entitlement, the `account_id` does not belong to the authenticated user, or the target list is read-only and its members cannot be modified. Clients can differentiate via the `code` value of the first item in `errors`. - `429` — Too many requests. Either the per-second rate limit or the monthly quota configured for the API key / OAuth application has been exceeded. Clients can differentiate via the `code` value of the first item in `errors`. - `500` — Internal server error - `504` — Server timeout --- [API](https://skmtc.net/leadfeeder/apis/leadfeeder-public-api.md) · [All operations](https://skmtc.net/leadfeeder/apis/leadfeeder-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/leadfeeder/leadfeeder-public-api/revisions/9e2e63ba2a4e/schema)