> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paraform.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get started with an agency API key

> Generate an agency key, check it, and make your first Agency API calls.

An agency API key calls the Paraform API **as your agency's integration**, not as any one person. Use it to connect your CRM or internal tools to your agency's Talent Network and roles.

<Warning>
  Only **agency owners** can generate agency API keys. If you're an agency member, ask an owner of your agency to create one for you.
</Warning>

<Note>
  Paraform enables API access per agency. If you're an owner and don't see the **API Keys** tab, ask your Paraform contact.
</Note>

<Steps>
  <Step title="Generate a key">
    Open the **API Keys** tab of your agency settings (`/agency/api-keys`) and create a key. Give it a name and choose its scopes:

    | Scope | Lets the key |
    | - | - |
    | `talent_network:read` | Read your agency's Talent Network data, such as members, submission batches, and candidate preferences. Every agency key carries this scope. |
    | `talent_network:write` | Upload resumes, submit candidates, and update candidate preferences, fast track, or market status |
    | `agency_roles:read` | Read roles on behalf of an approved member of your agency |

    The `talent_network:*` scopes are offered only when your agency has Talent Network access.

    The full key is shown **once**. Copy it into a secrets manager or environment variable straight away. Only use it from your servers, never from browser or mobile code.
  </Step>

  <Step title="Check it works">
    ```bash theme={null}
    export PARAFORM_API_KEY="pf_live_…"

    curl "https://external-api.paraform.com/api/external/v1/identity" \
      -H "Authorization: Bearer $PARAFORM_API_KEY"
    ```

    The response has `principal: "agency"`, your `agencyId`, the key's `name`, and its effective `scopes`. Any valid key can call `GET /identity`, whatever scopes it holds.
  </Step>

  <Step title="Make your first call">
    List the candidates your agency has in the talent network:

    ```bash theme={null}
    curl "https://external-api.paraform.com/api/external/v1/talent-network/candidates" \
      -H "Authorization: Bearer $PARAFORM_API_KEY"
    ```

    Then continue with [Submit candidates](/agency/guides/submit-candidates), [Check network membership](/agency/guides/network-membership), or [Read agency roles](/agency/guides/agency-roles).
  </Step>
</Steps>

## What an agency key can see

* **Only your own agency's data.** Talent Network endpoints return your agency's candidates only. A candidate in the network through a different agency looks the same as someone who isn't in the network.
* **Roles through a member.** Agency role endpoints read roles as one of your approved members sees them. You choose the member with `recruiterEmail` on each call. See [Read agency roles](/agency/guides/agency-roles).

## Managing keys

* Your agency can hold up to 50 active keys. Revoke unused ones on the **API Keys** tab.
* You can give a key an expiry date when you create it.
* A key stops working (`401`) if it's revoked or expires.
* Agency keys are separate from [personal API keys](/recruiter/guides/personal-api-keys). Personal keys can't call agency endpoints.

Rate limits, errors, and pagination work the same as for every key. See [Rate limits](/rate-limits), [Errors](/errors), and [Pagination](/pagination).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.