--- title: "Register a new link" method: POST path: "/api/links/" tags: ["Links"] --- # Register a new link `POST /api/links/` ## โ–ถ๏ธ Usage Register a new link (a connection between your user and their institution) using the Belvo API. > ๐Ÿ‘ We really recommend using our Connect Widget to handle link creation and link status updates. To make things easier, we've included custom examples for the links you can create for each of our products. Just click on the type of link you want to create in the **Body Params** section below. ## Request body - union - LinksRequestEmploymentBrazil โ€” The request body to create a link for employment institutions in Brazil. - `institution` string, required โ€” The Belvo name for the institution. For employment institutions in Brazil, you can select the following institutions: - `inss_br_employment` - `username` string, required โ€” The user's CPF (ID) used to log in to the institution. You can provide this either as 11 characters or with the format `XXX.XXX.XXX-XX`. - `password` string, password, required โ€” The user's password used to log in to the institution. - `external_id` string โ€” An additional identifier for the link, provided by you, to store in the Belvo database. **Cannot** include any Personal Identifiable Information (PII). **Must** be at least three characters long. If we identify that the identifier contains PII, we will force a `null` value. For more information, see our Link creation article. - `access_mode` 'single' | 'recurrent' โ€” The type of link to create. - Use `single` to do ad hoc one-time POST requests for accounts, owners, and transactions. - Use `recurrent` to have Belvo access information on a recurrent basis so you always have fresh account, owner, balance, and transaction data. For more information, see our Links article. - `fetch_resources` string[] โ€” An array of resources that you would like to receive a historical update for. For **Employments Brazil** (INSS), you can select the following resources: - `EMPLOYMENTS` - `OWNERS` - `credentials_storage` string โ€” Indicates whether or not to store credentials (and the duration for which to store the credentials). - For recurrent links, this is set to `store` by default (and cannot be changed). - For single links, this is set to `365d` by default. Can be either: - `store` to store credentials (until the link is deleted) - `nostore` to not store credentials - Any value between `1d` and `365d` to indicate the number of days you want the credentials to be stored. For more information, check out the credentials_storage section of our Data retention controls article. - `stale_in` string โ€” Indicates how long any user-derived data should be stored in Belvo's database for the link (both single and recurrent). For example, if you send through `90d`, Belvo will remove any data from its database relating to the user after 90 days. For more information, check out the stale_in section of our Data retention controls article. > ๐Ÿ“˜ Info > > Belvo will only remove data for links that have not been updated in the period you provide in `stale_in`. Belvo will only remove data for links that have not been updated in the period you provide in `stale_in`. By default Belvo stores user data for 365 days, unless the link is deleted. - LinksRequestEmploymentMexico โ€” The request body to create a link for employment institutions in Mexico. - `institution` string, required โ€” The Belvo name for the institution. For employment institutions in Mexico, you can select the following institutions: - `imss_mx_employment` - `issste_mx_employment` - `planet_mx_employment` (Sandbox institution) - `username` string, required โ€” The user's CURP (ID) used to log in to the institution. - `username2` string โ€” The user's email address used to log in to the institution. Note required for `issste_mx_employment`. - `external_id` string โ€” An additional identifier for the link, provided by you, to store in the Belvo database. **Cannot** include any Personal Identifiable Information (PII). **Must** be at least three characters long. If we identify that the identifier contains PII, we will force a `null` value. For more information, see our Link creation article. - `access_mode` 'single' | 'recurrent' โ€” The type of link to create. - Use `single` to do ad hoc one-time POST requests for accounts, owners, and transactions. - Use `recurrent` to have Belvo access information on a recurrent basis so you always have fresh account, owner, balance, and transaction data. For more information, see our Links article. - `fetch_resources` string[] โ€” An array of resources that you would like to receive a historical update for. For **Employment Records Mexico** (IMSS and ISSSTE), you can select the following resources: - `EMPLOYMENT_RECORDS` Additionally, you can opt-in to the following Employment Record specific resources (contact your representative as additional costs apply): - `CURRENT_EMPLOYMENTS` (IMSS only) - `EMPLOYMENT_METRICS` (IMSS only) - `credentials_storage` string โ€” Indicates whether or not to store credentials (and the duration for which to store the credentials). - For recurrent links, this is set to `store` by default (and cannot be changed). - For single links, this is set to `365d` by default. Can be either: - `store` to store credentials (until the link is deleted) - `nostore` to not store credentials - Any value between `1d` and `365d` to indicate the number of days you want the credentials to be stored. For more information, check out the credentials_storage section of our Data retention controls article. - `stale_in` string โ€” Indicates how long any user-derived data should be stored in Belvo's database for the link (both single and recurrent). For example, if you send through `90d`, Belvo will remove any data from its database relating to the user after 90 days. For more information, check out the stale_in section of our Data retention controls article. > ๐Ÿ“˜ Info > > Belvo will only remove data for links that have not been updated in the period you provide in `stale_in`. Belvo will only remove data for links that have not been updated in the period you provide in `stale_in`. By default Belvo stores user data for 365 days, unless the link is deleted. - LinksRequestFiscalMexico โ€” The request body to create a link for fiscal institutions in Mexico. - `institution` string, required โ€” The Belvo name for the institution. For fiscal institutions in Mexico, you can select the following institutions: - `sat_mx_fiscal` - `tatooine_mx_fiscal` (Sandbox institution) - `username` string, required โ€” The user's RFC (tax ID) used to log in to the institution. - `password` string, password, required โ€” The user's password used to log in to the institution. - `external_id` string โ€” An additional identifier for the link, provided by you, to store in the Belvo database. **Cannot** include any Personal Identifiable Information (PII). **Must** be at least three characters long. If we identify that the identifier contains PII, we will force a `null` value. For more information, see our Link creation article. - `access_mode` 'single' | 'recurrent' โ€” The type of link to create. - Use `single` to do ad hoc one-time POST requests for accounts, owners, and transactions. - Use `recurrent` to have Belvo access information on a recurrent basis so you always have fresh account, owner, balance, and transaction data. For more information, see our Links article. - `fetch_resources` string[] โ€” An array of resources that you would like to receive a historical update for. For **Fiscal Mexico** (SAT), you can select the following resources: - `FINANCIAL_STATEMENTS` - `INVOICES` - `TAX_COMPLIANCE_STATUS` - `TAX_RETENTIONS` - `TAX_RETURNS` - `TAX_STATUS` - `credentials_storage` string โ€” Indicates whether or not to store credentials (and the duration for which to store the credentials). - For recurrent links, this is set to `store` by default (and cannot be changed). - For single links, this is set to `365d` by default. Can be either: - `store` to store credentials (until the link is deleted) - `nostore` to not store credentials - Any value between `1d` and `365d` to indicate the number of days you want the credentials to be stored. For more information, check out the credentials_storage section of our Data retention controls article. - `stale_in` string โ€” Indicates how long any user-derived data should be stored in Belvo's database for the link (both single and recurrent). For example, if you send through `90d`, Belvo will remove any data from its database relating to the user after 90 days. For more information, check out the stale_in section of our Data retention controls article. > ๐Ÿ“˜ Info > > Belvo will only remove data for links that have not been updated in the period you provide in `stale_in`. Belvo will only remove data for links that have not been updated in the period you provide in `stale_in`. By default Belvo stores user data for 365 days, unless the link is deleted. ## Response `201` Created - Link - `id` string, uuid โ€” Belvo's unique identifier for the current item. - `institution` string โ€” Belvo's name for the institution. - `access_mode` 'single' | 'recurrent' | 'null', nullable โ€” The link type. For more information, see our Links article. We return one of the following enum values: - `single` - `recurrent` - `null` - `last_accessed_at` string, date-time, nullable โ€” The ISO-8601 timestamp of Belvo's most recent successful access to the institution for the given link. - `created_at` string, date-time โ€” The ISO-8601 timestamp of when the data point was created in Belvo's database. - `external_id` string โ€” An additional identifier for the link, provided by you, to store in the Belvo database. **Cannot** include any Personal Identifiable Information (PII). **Must** be at least three characters long. If we identify that the identifier contains PII, we will force a `null` value. For more information, see our Link creation article. - `institution_user_id` string โ€” > ๐Ÿ“˜ Info > > Only applicable for links created **after 08-02-2022**. A unique 44-character string that can be used to identify a user at a given institution. ๐Ÿ“š Check out our Avoiding duplicated links DevPortal article for more information and tips on how to use it. - `status` 'valid' | 'invalid' | 'unconfirmed' | 'token_required' โ€” The current status of the link. For more information, see our Link article in the devportal. We return one of the following values: - `valid` - `invalid` - `unconfirmed` - `token_required` - `created_by` string, uuid โ€” The unique ID for the user that created this item. - `refresh_rate` '6h' | '12h' | '24h' | '7d' | '30d' | 'null', nullable โ€” The update refresh rate for the recurrent link. For more information, check out our recurrent link documentation in our DevPortal. We return one of the following enum values: - `6h` - `12h` - `24h` - `7d` (default) - `30d` (once a month) - `null` (for single links) - `credentials_storage` string โ€” Indicates whether or not to store credentials (and the duration for which to store the credentials). - For recurrent links, this is set to `store` by default (and cannot be changed). - For single links, this is set to `365d` by default. Can be either: - `store` to store credentials (until the link is deleted) - `nostore` to not store credentials - Any value between `1d` and `365d` to indicate the number of days you want the credentials to be stored. For more information, check out the credentials_storage section of our Data retention controls article. - `fetch_resources` string[] โ€” An array of resources that you will receive a historical update for. - `stale_in` string โ€” Indicates how long any user-derived data should be stored in Belvo's database for the link (both single and recurrent). For example, if you send through `90d`, Belvo will remove any data from its database relating to the user after 90 days. For more information, check out the stale_in section of our Data retention controls article. > ๐Ÿ“˜ Info > > Belvo will only remove data for links that have not been updated in the period you provide in `stale_in`. Belvo will only remove data for links that have not been updated in the period you provide in `stale_in`. By default Belvo stores user data for 365 days, unless the link is deleted. ## Other responses - `400` โ€” Bad request error - `401` โ€” Unauthorized - `403` โ€” Access to Belvo API denied - `404` โ€” Not Found Error - `408` โ€” Request Timeout - `428` โ€” MFA Token Required - `500` โ€” Unexpected Error --- [API](https://skmtc.net/belvo/apis/belvo-api-docs.md) ยท [All operations](https://skmtc.net/belvo/apis/belvo-api-docs/llms.txt) ยท [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/belvo/belvo-api-docs/revisions/e82dca4a4b97/schema)