> For the complete documentation index, see [llms.txt](https://firstoken.gitbook.io/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://firstoken.gitbook.io/api-docs/how-to/create-an-inbound-route.md). # Create an Inbound Route An Inbound Route is the entry point through which card data is received by Firstoken for tokenization. Each route defines how data is received, what token type is generated, and how the response is structured. Inbound Routes are used in direct API integrations, SDK implementations, and as part of the Reverse Proxy product. {% hint style="info" %} If you plan to assign a Proxy to this route or use a custom domain, create the Proxy first. See [Create a Proxy](/api-docs/how-to/create-a-proxy.md). {% endhint %} **Steps** 1. Log in to the Firstoken Console. 2. Navigate to **Inbound Routes** and click **+ New Inbound Route**. 3. Complete Route Information. 4. Complete Configure Rules. 5. Click Create Inbound Route. A modal displays the Route URL — copy it or\ access it again at any time from the Edit view. The Route ID is available\ in the Inbound Routes table and is required for your integration. *** ### Route Information | Field | Required | Description | | ------------------- | :------: | ---------------------------------------------------------------------------------------------------------------------- | | **Name** | Yes | A label to identify this route in the Console. | | **Description** | No | A note for internal reference. | | **URL** | — | Generated automatically. Available in the confirmation modal after creation and in the Edit view. | | **Proxy** | No | Select a previously created Proxy to forward the tokenized request. Only proxies with method `POST` are shown. | | **Custom Hostname** | No | When enabled, the route operates as a Domain Inbound Route on the client's own domain. See Domain Inbound Route below. | | **IP Whitelisting** | No | Restrict incoming requests to specific IP addresses or CIDR ranges. | {% hint style="info" %} The Route URL is generated when the Inbound Route is created. It is not visible during the creation flow. It appears in the confirmation modal after saving, and is accessible at any time from the Edit view. {% endhint %} *** ### Configure Rules #### Token Type Select whether the token generated by this route is **Temporal** or **Permanent**. | Option | Description | | ------------- | ------------------------------------------------------ | | **Temporal** | The token expires after a configured TTL. | | **Permanent** | The token does not expire. Enables additional options. | If **Permanent** is selected, the **Persistent Token** toggle becomes available. When enabled, Firstoken reuses an existing token if the same card data has been tokenized before, instead of generating a new one. *** #### Path and Fields in JSON Defines which path on the route receives card data and which fields in the request body contain that data.

Field	Temporal	Permanent	Description
Path	Conditional	Conditional	Required when Custom Hostname is enabled. Defines the path where card data is received. Read-only otherwise.
Card number	Yes	Yes	JSON path to the card number field in the request body.
Cardholder name	Yes	Yes	JSON path to the cardholder name field.
Expiration month	Yes	Yes	JSON path to the expiration month field.
Expiration year	Yes	Yes	JSON path to the expiration year field.
CVV	Yes	No	JSON path to the CVV field.
Tags	No	Yes	JSON path to a tags field.

*** #### Overwritten Fields The JSON key in the response body where Firstoken writes the tokenized output. This field replaces the original card data in the forwarded request. Click **+ Add a field** to include additional overwritten fields if needed. *** #### Additional Fields by Token Type

Field	Temporal	Permanent	Description
TTL	Yes	No	Time-to-live for the token. Set a numeric value and select the unit (minutes, hours, etc.).
Schema	No	Yes	Format of the generated token. Options: `sixTOKENfour`, `sixANTOKENfour`, `UUID`.
Include Metadata	Conditional	Conditional	When enabled, Firstoken includes additional token metadata in the response.
Field name	Yes	Yes	Required when Include Metadata is enabled. Specifies the key in the response body where metadata is written.

{% hint style="info" %} When **Include Metadata** is enabled, the metadata also includes the 8-digit BIN if the feature is active on your account. For details, see [8-Digit BIN Support](/api-docs/guides/8-digit-bin-support.md). {% endhint %} *** ### Domain Inbound Route Enabling the **Custom Hostname** toggle converts the route into a Domain Inbound Route. This type is used exclusively with the Reverse Proxy product, and allows the route to operate on the client's own domain instead of a Firstoken-hosted URL. When Custom Hostname is enabled: * The **Proxy** field becomes required. Only proxies with method `POST` are shown. * The Route URL format changes to `https://{routeId}.routes.firstoken.co` * The route supports **multiple path configurations** within the same Inbound Route. Use **+ Add a configuration** to add additional paths. {% hint style="info" %} Each path configuration is independent. Token type, field mapping, schema, and metadata settings are defined separately per path. {% endhint %} {% hint style="danger" %} The path defined in each configuration and the destination path in the associated Proxy must always differ. Configuring the same host and path for both causes an infinite routing loop. {% endhint %} *** ### Route URL Reference

Type	Format
Standard	`https://api.firstoken.co/routes/{routeId}`
Domain	`https://{routeId}.routes.firstoken.co`

The `{routeId}` is the same identifier in both cases. In standard routes it appears as a path segment; in Domain routes it appears as a subdomain. *** ### Verify Tokens After the Inbound Route receives a request and tokenizes the card data, verify the result according to the token type configured:

Token type	How to verify
Permanent	Firstoken Console > Tokens, or via the TaaS API.
Temporary	Transactions API using the transaction ID returned in the inbound request.

*** ### Related Pages * [Create a Proxy](/api-docs/how-to/create-a-proxy.md) * [Implementing Captures SDK JS](/api-docs/guides/implementing-captures-sdk-js.md) * [Implementing Reverse Proxy](/api-docs/guides/implementing-reverse-proxy.md) * [Configure a Custom Domain](/api-docs/guides/configure-a-custom-domain.md)