# Historical Headcount API

This section covers general details about Historical Headcount API.

{% hint style="info" %}

#### Find out more

Contact our sales team to get access to more information about this API:

<a href="https://coresignal.com/contact-us/?utm_source=web&#x26;utm_medium=public-docs&#x26;utm_campaign=data-consultation" class="button primary">Contact sales</a>
{% endhint %}

## Historical headcount API endpoints

Historical headcount data enables you to see how companies’ social media following and headcount numbers have changed over time.

Retrieve the Historical headcount data using **two collection** endpoints. Collect the data using either `company ID` or `company shorthand name`.

| Request type | Endpoint                                              |
| ------------ | ----------------------------------------------------- |
| GET          | */v2/historical\_headcount/collect/{company\_id}*     |
| GET          | */v2/historical\_headcount/collect/{shorthand\_name}* |

\*📌 Full profile URL example: \_[www.professional-network.com/example-company\_.\\](http://www.professional-network.com/example-company_.\\)
Shorthand name example: *example-company*.

## Request types

{% hint style="warning" %}
All Historical headcount API requests must be made over HTTPS. Requests made over HTTP will fail or be redirected to HTTPS.
{% endhint %}

Historical headcount API supports GET requests only.

## Rate limits

Historical headcount API endpoints restrict the number of requests allowed per second.

{% columns %}
{% column %}
Collection API endpoints
{% endcolumn %}

{% column %}
54 requests per second
{% endcolumn %}
{% endcolumns %}

## Credits

**One** collect credit is deducted for **one successful (200) request** in the collection endpoints:

* *​*/*v2/historical\_headcount/collect/{company\_id}*
* /*​v2/historical\_headcount/collect/{shorthand\_name}*

## FAQ

The data you receive from the Historical headcount API differs from company data.

<details>

<summary>How often is the data updated?</summary>

Historical headcount data is updated once a month (at the beginning of the month).

</details>

## Dictionary

| Data field                 | Description                                                                                                                                           | Data type |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `created`                  | Record creation timestamp                                                                                                                             | String    |
| `company_id`               | Company record ID assigned in the database                                                                                                            | Integer   |
| `source_id`                | Professional network in-house company ID (static)                                                                                                     | Integer   |
| `professional_network_url` | <p>Professional network profile URL<br><strong>Note</strong>: seen as <code>canonical\_url</code> in our company data</p>                             | String    |
| `shorthand_name`           | <p>Dynamic part of the URL used to identify companies<br><strong>Note</strong>: seen as <code>company\_shorthand\_name</code> in our company data</p> | String    |
| `canonical_shorthand_name` | Most recent version of the `shorthand_name`                                                                                                           | String    |
| `name`                     | Name                                                                                                                                                  | String    |
| `website`                  | Website                                                                                                                                               | String    |
| `size`                     | Employee count                                                                                                                                        | String    |
| `industry`                 | Associated industry                                                                                                                                   | String    |
| `type`                     | Type                                                                                                                                                  | String    |
| `location`                 | Location                                                                                                                                              | String    |
| `country`                  | Location (country)                                                                                                                                    | String    |
| `headcount`                | Headcount                                                                                                                                             | Integer   |
| `follower_count`           | Profile follower count                                                                                                                                | Integer   |

### Response sample

{% hint style="info" %}
All personal/company information mentioned within this context is entirely fictional and is solely intended for illustrative purposes.
{% endhint %}

{% code title="Response example" %}

```json
[
  {
    "created": "2023-12-19 08:42:33",
    "company_id": 8579547,
    "source_id": 1586,
    "professional_network_url": "https://www.professional_network.com/company/example-company",
    "shorthand_name": "example-company",
    "canonical_shorthand_name": "example-company",
    "name": "Amazon",
    "website": "https://www.example-company.com/",
    "size": "10,001+ employees",
    "industry": "Software Development",
    "type": "Private Company",
    "location": "San Francisco, CA",
    "country": "United States",
    "headcount": 119730,
    "follower_count": 229985793
  },
  {
    "created": "2023-11-21 09:54:07",
    "company_id": 8579547,
    "source_id": 1586,
    "professional_network_url": "https://www.professional_network.com/company/example-company",
    "shorthand_name": "example-company",
    "canonical_shorthand_name": "example-company",
    "name": "Amazon",
    "website": "https://www.about-example-company.com/",
    "size": "10,001+ employees",
    "industry": "Software Development",
    "type": "Private Company",
    "location": "San Francisco, CA",
    "country": "United States",
    "headcount": 86538,
    "follower_count": 1711354
  },
  {
    "created": "2023-10-08 18:22:51",
    "company_id": 8579547,
    "source_id": 1586,
    "professional_network_url": "https://www.professional_network.com/company/example-company",
    "shorthand_name": "example-company",
    "canonical_shorthand_name": "example-company",
    "name": "Amazon",
    "website": "https://www.example-company.com/",
    "size": "10,001+ employees",
    "industry": "Software Development",
    "type": "Private Company",
    "location": "San Francisco, CA",
    "country": "United States",
    "headcount": 10350,
    "follower_count": 12866
  }
. . .
]
```

{% endcode %}