# Create an identity You need to create an identity for the beneficiary or originating party so they can be identified in the payment request. Identities in Ripple Payments are objects that correspond to payment participants, such as payment originators and beneficiaries of payments. They contain all of the personally identifiable information (PII) connected to a specific individual or business to ensure proper compliance and proper routing. Note While this tutorial focuses on creating a `BENEFICIARY`, the process is similar for an `ORIGINATOR`. This guide walks you through the API calls required to create an identity. 1. [Get data requirements](#get-data-requirements) used to create an identity based on your workflow. 2. [Examine the response](#example-requirements-response) and transform them into a compatible JSON format. 3. [Create a new identity](#create-a-new-identity) to serve as an originator or beneficiary. ## Prerequisite You should have the following items before you continue: * An [access token](/products/payments-direct/api-docs/tutorials/request-an-access-token) to access secured API endpoints. * The value for `partner-name` provided by your Ripple Liaison. Note The `partner-name` defines which payout partner is used to complete your transaction. ## Get data requirements Use the [get data requirements](/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/data-requirements/getdatarequirements) operation to retrieve the data requirements based on your use case. Your requirements will be different You should get the latest data requirements each time a new identity is created as they differ depending on the destination country and currencies. ### Example requirements request In this example, we'll go through the process of creating a `BENEFICIARY` in Austria configured for a `BANK` payout in `EUR`. To achieve this we'll assign the following example values: | Field name | Example value | Description | | --- | --- | --- | | payout-country | `AT` | The destination country for the payment, in this case, Austria. | | use-case | `B2B` | The type of use-case, in this case, B2B (a business originator paying a business beneficiary). | | payout-currency | `EUR` | The payout currency, in this case, euro. | | payout-category | `BANK` | The payout category, Ripple Payments uses the bank payout. | | partner-name | `SamplePartner` | Specifies the payout partner, this tutorial uses SamplePartner. | | field-category | `BENEFICIARY` | Specifies the type of identity, in this case, a beneficiary. | | flow | `RPD` | Specifies the type of payment flow, currently RPD. | ### Example requirements response The get data-requirements response contains a list of field names and values. You use these fields to create a JSON payload compatible with the `piiData` object. **Example response** : This example is truncated for brevity. ```json { "supportedUseCase": "B2B", "payoutCountry": "AT", "payoutCurrency": "EUR", "dataRequirements": [ { "fieldCategory": "BENEFICIARY", "fieldName": "Cdtr.Nm", "fieldType": "REQUIRED", "fieldDataType": "STRING", "fieldMinLength": 0, "fieldMaxLength": 100, "fieldDescription": "Beneficiary Business Legal Name", "fieldHelpText": "The legal name of the beneficiary business" }, { "fieldCategory": "BENEFICIARY", "fieldName": "CdtrAcct.Ccy", "fieldType": "REQUIRED", "fieldDataType": "STRING", "fieldMinLength": 0, "fieldMaxLength": 6, "fieldDescription": "Business Account Currency", "fieldHelpText": "The beneficiary business' account's currency associated with the Account Identification Scheme" }, { "fieldCategory": "BENEFICIARY", "fieldName": "CdtrAgt.FinInstnId.Nm", "fieldType": "REQUIRED", "fieldDataType": "STRING", "fieldMinLength": 0, "fieldMaxLength": 50, "fieldDescription": "Beneficiary's Bank name.", "fieldHelpText": "Name by which the party is known and which is usually used to identify the party." } ] } ``` #### Example transformed object You need to transform the response by following the guidelines within the response, into a `piiData`-compatible JSON object. * See [working with piiData](/products/payments-direct/api-docs/working-with-piidata-object) for more information. * See [data requirements definitions](/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/data-requirements/getdatarequirements) for more information. ```json { "identityType": "BENEFICIARY", "nickName": "Successful Business Beneficiary", "useCaseType": "BUSINESS", "piiData": { "Cdtr": { "Nm": "Success Co.", "CtctDtls": { "MobNb": "+11234567890", "EmailAdr": "test@test.com" }, "CtryOfRes": "AT", "Id": { "OrgId": { "Othr": { "Id": "1234567890", "SchmeNm": { "Cd": "CINC" } }, "RelShipToDbtr": "CUST" } }, "PstlAdr": { "AdrLine": [ "1234 Business Beneficiary Ave" ], "PstCd": "02125", "TwnNm": "Boston" } }, "CdtrAcct": { "Ccy": "US", "Id": { "IBAN": "1234123412341234", "Othr": { "SchmeNm": { "Cd": "BBAN" } } } }, "CdtrAgt": { "BrnchId": { "PstlAdr": { "Ctry": "US" } }, "FinInstnId": { "Nm": "Bank of Massachusetts", "Othr": { "Id": "123456" } } } } } ``` ## Create a new identity Now it's time to take piiData JSON object schema we transformed from the response to our get data requirements request to create an identity token that we'll use for accepting a payment quote. This example uses the [create a new identity](/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/identities/createidentity) operation to create a new identity of the type `BENEFICIARY`. * `identityType` : This example uses `BENEFICIARY` to create a beneficiary identity. * `nickName` : This example uses a recognizable name such as `Successful Business Beneficiary`. * `piiData` : Populate this object with the [required PII information](/products/payments-direct/api-docs/working-with-piidata-object) for the chosen `identityType`. ## Identity response Store the `identityId` value for use later with the [accept quote](/products/payments-direct/api-docs/tutorials/create-a-payment#accept-a-quote) operation. The accept quote operation's request body requires a `user_info` object containing this value as the `beneficiary_token` property. ```json { "identityId": "22222222-aaaa-2222-bbbb-222222222222", "version": 2 } ``` Tip You can use the `identityId` with the [get an identity by ID](/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/identities/getidentitybyid) operation to view the newly created identity.