API Reference

Welcome to the Portabl Core™ API documentation for managing collection and reception of KYC data. We will cover the necessary steps for integrating our API into your application to seamlessly manage your user's KYC data. KYC, or Know Your Customer, is a critical step in financial transactions to verify the identity and legitimacy of your users.

Our API enables you to collect and receive KYC data securely, efficiently, and in compliance with regulatory requirements. By integrating our API, you can streamline your KYC process, reduce manual errors, and improve user experience.

To get started, you will need to authenticate with our API using your API key. Once authenticated, you can use our API endpoints to initiate KYC data collection, receive user data, and manage the status of KYC requests. Our API supports various KYC documents, including government-issued IDs, proof of address, and other relevant documents.

Auth

Get Access Token

The Portabl Core™ API uses API keys to authenticate requests. You can view and manage your API keys in the Stripe Dashboard. Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth. Authentication to the API is performed via HTTP Basic Auth.

BODY
OptionTypeDescription
clientIdstringYour Portabl Core API client id
clientSecretstringYour Portabl Core API client secret
POSThttps://api.ngrok.io/api/v1/provider/token
curl -X POST "https://api.ngrok.io/api/v1/provider/token" / 
--data-raw {
  "clientId": "<YOUR clientId>",
  "clientSecret": "<YOUR clientSecret>"
}
RESPONSE
{
    "tokenType": "Bearer",
    "scope": "read:settings update:settings read:members create:member-invitations read:member-invitations update:member-invitations delete:member-invitations read:identifiers update:identifiers read:trusted-issuers create:data-profiles read:data-profiles read:credential-manifests read:presentation-definitions read:verifiable-documents read:evidence-attachments verify:credentials verify:presentations read:provider-users read:provider-user-settings upsert:provider-users upsert:provider-user-claims read:provider-user-sync-sessions create:provider-user-sync-sessions start:provider-user-sync-sessions read:provider-sync-data read:provider-sync-sessions",
    "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ikp2UnZvZVJ0ZDBpZ215R3EyVkJtbSJ9.eyJodHRwczovL2dldHBvcnRhYmwuY29tL3RlbmFudElkIjoicHJvdmlkZXItYTVlOThiMGEtNDIwMS00ODA2LWI0OTYtYjVmN2VkMDc0Yjc0IiwiaXNzIjoiaHR0cHM6Ly9kZXYtYXV0aC5nZXRwb3J0YWJsLmNvbS8iLCJzdWIiOiJqOWhHZFRQUE5zdTdId0czV2xRTEpBQmE5UHl0bnh1ZUBjbGllbnRzIiwiYXVkIjoiaHR0cHM6Ly9kZXYtYXBpLmdldHBvcnRhYmwuY29tIiwiaWF0IjoxNjgyMzg5NTAwLCJleHAiOjE2ODI0NzU5MDAsImF6cCI6Imo5aEdkVFBQTnN1N0h3RzNXbFFMSkFCYTlQeXRueHVlIiwic2NvcGUiOiJyZWFkOnNldHRpbmdzIHVwZGF0ZTpzZXR0aW5ncyByZWFkOm1lbWJlcnMgY3JlYXRlOm1lbWJlci1pbnZpdGF0aW9ucyByZWFkOm1lbWJlci1pbnZpdGF0aW9ucyB1cGRhdGU6bWVtYmVyLWludml0YXRpb25zIGRlbGV0ZTptZW1iZXItaW52aXRhdGlvbnMgcmVhZDppZGVudGlmaWVycyB1cGRhdGU6aWRlbnRpZmllcnMgcmVhZDp0cnVzdGVkLWlzc3VlcnMgY3JlYXRlOmRhdGEtcHJvZmlsZXMgcmVhZDpkYXRhLXByb2ZpbGVzIHJlYWQ6Y3JlZGVudGlhbC1tYW5pZmVzdHMgcmVhZDpwcmVzZW50YXRpb24tZGVmaW5pdGlvbnMgcmVhZDp2ZXJpZmlhYmxlLWRvY3VtZW50cyByZWFkOmV2aWRlbmNlLWF0dGFjaG1lbnRzIHZlcmlmeTpjcmVkZW50aWFscyB2ZXJpZnk6cHJlc2VudGF0aW9ucyByZWFkOnByb3ZpZGVyLXVzZXJzIHJlYWQ6cHJvdmlkZXItdXNlci1zZXR0aW5ncyB1cHNlcnQ6cHJvdmlkZXItdXNlcnMgdXBzZXJ0OnByb3ZpZGVyLXVzZXItY2xhaW1zIHJlYWQ6cHJvdmlkZXItdXNlci1zeW5jLXNlc3Npb25zIGNyZWF0ZTpwcm92aWRlci11c2VyLXN5bmMtc2Vzc2lvbnMgc3RhcnQ6cHJvdmlkZXItdXNlci1zeW5jLXNlc3Npb25zIHJlYWQ6cHJvdmlkZXItc3luYy1kYXRhIHJlYWQ6cHJvdmlkZXItc3luYy1zZXNzaW9ucyIsImd0eSI6ImNsaWVudC1jcmVkZW50aWFscyIsInBlcm1pc3Npb25zIjpbInJlYWQ6c2V0dGluZ3MiLCJ1cGRhdGU6c2V0dGluZ3MiLCJyZWFkOm1lbWJlcnMiLCJjcmVhdGU6bWVtYmVyLWludml0YXRpb25zIiwicmVhZDptZW1iZXItaW52aXRhdGlvbnMiLCJ1cGRhdGU6bWVtYmVyLWludml0YXRpb25zIiwiZGVsZXRlOm1lbWJlci1pbnZpdGF0aW9ucyIsInJlYWQ6aWRlbnRpZmllcnMiLCJ1cGRhdGU6aWRlbnRpZmllcnMiLCJyZWFkOnRydXN0ZWQtaXNzdWVycyIsImNyZWF0ZTpkYXRhLXByb2ZpbGVzIiwicmVhZDpkYXRhLXByb2ZpbGVzIiwicmVhZDpjcmVkZW50aWFsLW1hbmlmZXN0cyIsInJlYWQ6cHJlc2VudGF0aW9uLWRlZmluaXRpb25zIiwicmVhZDp2ZXJpZmlhYmxlLWRvY3VtZW50cyIsInJlYWQ6ZXZpZGVuY2UtYXR0YWNobWVudHMiLCJ2ZXJpZnk6Y3JlZGVudGlhbHMiLCJ2ZXJpZnk6cHJlc2VudGF0aW9ucyIsInJlYWQ6cHJvdmlkZXItdXNlcnMiLCJyZWFkOnByb3ZpZGVyLXVzZXItc2V0dGluZ3MiLCJ1cHNlcnQ6cHJvdmlkZXItdXNlcnMiLCJ1cHNlcnQ6cHJvdmlkZXItdXNlci1jbGFpbXMiLCJyZWFkOnByb3ZpZGVyLXVzZXItc3luYy1zZXNzaW9ucyIsImNyZWF0ZTpwcm92aWRlci11c2VyLXN5bmMtc2Vzc2lvbnMiLCJzdGFydDpwcm92aWRlci11c2VyLXN5bmMtc2Vzc2lvbnMiLCJyZWFkOnByb3ZpZGVyLXN5bmMtZGF0YSIsInJlYWQ6cHJvdmlkZXItc3luYy1zZXNzaW9ucyJdfQ.pjlBDRq0GYFJ6Jql666xfJG-VHYeuTZXN4dpQ6CH6dfUZsZPuN2i007jabKV80z-MjLjpf6Vo8r_UtAyFswEiyh7FcbnyKYQNKvxs7AkM2cOgxlOOpUKQxkpCyFOcI5ixVGtFiXv_DfZxJ3z_nL5G0n6sgZ1h8xxh51gYQVl1BIqkGUOlhx-73a04uGsAWmwj0xQepaiGokpdm9z7QtylcisLVXSVhvSBB1fy4yvgTEK9smKuzva7kPIRwmlQcIHTUGU2-D8a9A8Jm9zlymOSD8skhHsMlzBUW56Ous5HvO2e4V1ybrjobtwWozlniQQyubqdWSunoRKF2ZLkYUwsA",
    "expiresIn": 86400
  }

Users #### Get Users

Returns a list of existing users and their data.

GEThttps://api.ngrok.io/api/v1/provider/users
curl -X GET "https://api.ngrok.io/api/v1/provider/users" / 
-H "Authorization: Bearer <TOKEN>"
RESPONSE
{
  "users": [
    {
      "id": "string",
      "claims": {
        "firstName": "Liz",
        "lastName": "Lemon",
        "sex": "female",
        "birthDate": "string",
        "birthPlace": "string",
        "nationality": "string",
        "socialSecurityNumber": "string",
        "driverLicenseId": "string",
        "idCardNumber": "string",
        "passportNumber": "string",
        "residencePermitNumber": "string",
        "registrationAddressDetailsCountry": "string",
        "registrationAddressDetailsPostalCode": "string",
        "registrationAddressDetailsRegion": "string",
        "registrationAddressDetailsLocality": "string",
        "registrationAddressDetailsStreetAddress": "string",
        "emailAddress": "string",
        "phoneNumber": "string"
      },
      "settings": {
        "isSyncOn": "boolean"
      }
    }
  ]
}

Update or create a user

Returns a list of existing users and their data.

BODY
OptionTypeDescription
settings{ "isSyncOn": "boolean" }Settings for the user
PUThttps://api.ngrok.io/api/v1/provider/users/:user-id
curl -X PUT "https://api.ngrok.io/api/v1/provider/users/:user-id" / 
-H "Authorization: Bearer <TOKEN>"/ 
--data-raw {
  "settings": "<YOUR settings>"
}
RESPONSE
{
  "isSyncOn": "boolean"
}

Get user settings

Returns settings for a user.

GEThttps://api.ngrok.io/api/v1/provider/users/:user-id/settings
curl -X GET "https://api.ngrok.io/api/v1/provider/users/:user-id/settings" / 
-H "Authorization: Bearer <TOKEN>"
RESPONSE
{
  "isSyncOn": "boolean"
}

Update user settings

Updates settings for a user.

BODY
OptionTypeDescription
settings{ "isSyncOn": "boolean" }
PUThttps://api.ngrok.io/api/v1/provider/users/:user-id/settings
curl -X PUT "https://api.ngrok.io/api/v1/provider/users/:user-id/settings" / 
-H "Authorization: Bearer <TOKEN>"/ 
--data-raw {
  "settings": "<YOUR settings>"
}
RESPONSE
{
  "isSyncOn": "boolean"
}

Get user claims

Get claims for a user.

GEThttps://api.ngrok.io/api/v1/provider/users/:user-id/claims
curl -X GET "https://api.ngrok.io/api/v1/provider/users/:user-id/claims" / 
-H "Authorization: Bearer <TOKEN>"
RESPONSE
{
  "birthDate": "1970-11-27",
  "birthPlace": "PENNSYLVANIA, USA",
  "emailAddress": "liz.lemon@rock.com",
  "firstName": "Liz",
  "lastName": "Lemon",
  "nationality": "UNITED STATES OF AMERICA",
  "registrationAddressDetailsCountry": "USA",
  "registrationAddressDetailsLocality": "New York",
  "registrationAddressDetailsPostalCode": "10024",
  "registrationAddressDetailsRegion": "New York",
  "registrationAddressDetailsStreetAddress": "168 Riverside Drive, APT 2F",
  "sex": "female"
}

Update user claims

Update claims for a user.

BODY
OptionTypeDescription
claims{ "emailAddress": "string", "phoneNumber": "string", "firstName": "string", "lastName": "string", "sex": "string", "birthDate": "string", "birthPlace": "string", "nationality": "string", "socialSecurityNumber": "string", "registrationAddressDetails": { "country": "string", "region": "string", "postalCode": "string", "locality": "string", "streetAddress": "string" } }Claims to update for the user
PUThttps://api.ngrok.io/api/v1/provider/users/:user-id/claims
curl -X PUT "https://api.ngrok.io/api/v1/provider/users/:user-id/claims" / 
-H "Authorization: Bearer <TOKEN>"/ 
--data-raw {
  "claims": "<YOUR claims>"
}
RESPONSE
{
  "_id": "644694ceaf1e5a181722e38e",
  "userId": "4c0ac449-135d-45c8-81f3-a8e96a508c2b",
  "birthDate": "1970-11-27",
  "birthPlace": "PENNSYLVANIA, USA",
  "emailAddress": "liz.lemon@rock.com",
  "firstName": "Liz",
  "lastName": "Lemon",
  "nationality": "UNITED STATES OF AMERICA",
  "registrationAddressDetailsCountry": "USA",
  "registrationAddressDetailsLocality": "New York",
  "registrationAddressDetailsPostalCode": "10024",
  "registrationAddressDetailsRegion": "New York",
  "registrationAddressDetailsStreetAddress": "168 Riverside Drive, APT 2F",
  "sex": "female"
}

Get Datapoints

Returns a list of datapoints that define the claims and data we collect from your users when they perform sync or connect.existing users and their data.

GEThttps://api.ngrok.io/api/v1/provider/data-profiles/latest/datapoints
curl -X GET "https://api.ngrok.io/api/v1/provider/data-profiles/latest/datapoints" / 
-H "Authorization: Bearer <TOKEN>"
RESPONSE
{
  "datapoints": [
    {
      "id": "urn:uuid:d6716787-c611-4712-a67a-18232dd1ada8",
      "kind": "FirstName",
      "group": "FullName",
      "label": "First Name",
      "jsonPathArray": [
        "$.credentialSubject.firstName"
      ],
      "jsonSchema": {
        "type": "string"
      },
      "evidenceOptionality": "required"
    },
    {
      "id": "urn:uuid:b79325ee-f849-4405-a8d8-8c5c5b28854c",
      "kind": "LastName",
      "group": "FullName",
      "label": "Last Name",
      "jsonPathArray": [
        "$.credentialSubject.lastName"
      ],
      "jsonSchema": {
        "type": "string"
      },
      "evidenceOptionality": "required"
    },
    {
      "id": "urn:uuid:2361d635-e4e1-4fef-ad4e-6e175ced34db",
      "kind": "Sex",
      "group": "Sex",
      "label": "Sex",
      "jsonPathArray": [
        "$.credentialSubject.sex"
      ],
      "jsonSchema": {
        "type": "string"
      },
      "evidenceOptionality": "required"
    },
    {
      "id": "urn:uuid:7ec90475-b531-46d9-bcfa-ffc181e6fc2e",
      "kind": "BirthDate",
      "group": "BirthDate",
      "label": "Birth Date",
      "jsonPathArray": [
        "$.credentialSubject.birthDate"
      ],
      "jsonSchema": {
        "type": "string"
      },
      "evidenceOptionality": "required"
    },
    {
      "id": "urn:uuid:81541115-b511-483a-afc7-798a154ef7a8",
      "kind": "BirthPlace",
      "group": "BirthPlace",
      "label": "Birth Place",
      "jsonPathArray": [
        "$.credentialSubject.birthPlace"
      ],
      "jsonSchema": {
        "type": "string"
      },
      "evidenceOptionality": "required"
    },
    {
      "id": "urn:uuid:d999213b-6986-4793-b7c0-8de72297d40a",
      "kind": "Nationality",
      "group": "Nationality",
      "label": "Nationality",
      "jsonPathArray": [
        "$.credentialSubject.nationality"
      ],
      "jsonSchema": {
        "type": "string"
      },
      "evidenceOptionality": "required"
    },
    {
      "id": "urn:uuid:d38385e5-885b-42e7-a8da-bb1ef510f626",
      "kind": "RegistrationAddressDetailsCountry",
      "group": "RegistrationAddressDetails",
      "label": "Country",
      "jsonPathArray": [
        "$.credentialSubject.registrationAddressDetails.country"
      ],
      "jsonSchema": {
        "type": "string"
      },
      "evidenceOptionality": "required"
    },
    {
      "id": "urn:uuid:7b20fd47-4f8a-400f-87a8-0f582e27894a",
      "kind": "RegistrationAddressDetailsRegion",
      "group": "RegistrationAddressDetails",
      "label": "Region",
      "jsonPathArray": [
        "$.credentialSubject.registrationAddressDetails.region"
      ],
      "jsonSchema": {
        "type": "string"
      },
      "evidenceOptionality": "required"
    },
    {
      "id": "urn:uuid:d80d24c9-e14d-4746-a916-ed5d62be3883",
      "kind": "RegistrationAddressDetailsPostalCode",
      "group": "RegistrationAddressDetails",
      "label": "Postal Code",
      "jsonPathArray": [
        "$.credentialSubject.registrationAddressDetails.postalCode"
      ],
      "jsonSchema": {
        "type": "string"
      },
      "evidenceOptionality": "required"
    },
    {
      "id": "urn:uuid:96f47d30-71a5-4ee0-9cb3-9277f7367a52",
      "kind": "RegistrationAddressDetailsLocality",
      "group": "RegistrationAddressDetails",
      "label": "Locality",
      "jsonPathArray": [
        "$.credentialSubject.registrationAddressDetails.locality"
      ],
      "jsonSchema": {
        "type": "string"
      },
      "evidenceOptionality": "required"
    },
    {
      "id": "urn:uuid:bfd0e44f-c8de-4264-8f14-7f536f9ec9e4",
      "kind": "RegistrationAddressDetailsStreetAddress",
      "group": "RegistrationAddressDetails",
      "label": "Street Address",
      "jsonPathArray": [
        "$.credentialSubject.registrationAddressDetails.streetAddress"
      ],
      "jsonSchema": {
        "type": "string"
      },
      "evidenceOptionality": "required"
    },
    {
      "id": "urn:uuid:4d8a181c-117b-4b68-9e77-3005fd3c2372",
      "kind": "EmailAddress",
      "group": "EmailAddress",
      "label": "Email Address",
      "jsonPathArray": [
        "$.credentialSubject.emailAddress"
      ],
      "jsonSchema": {
        "type": "string"
      }
    }
  ]
}

Create Sync Session

Create the sync session that will be return an invitation that gets accepted by the FS User. This is the request that initiates the handshake.

https://api.ngrok.io/api/v1/provider/users/:user-id/sync-sessions
curl -X undefined "https://api.ngrok.io/api/v1/provider/users/:user-id/sync-sessions" / 
-H "Authorization: Bearer <TOKEN>"
RESPONSE
{
  "syncSession": {
    "id": "add04a97-161b-448a-9b89-10ae5b220c26",
    "userId": "4c0ac449-135d-45c8-81f3-a8e96a508c2b",
    "didcommSessionIds": [],
    "createdAt": "2023-04-24T15:16:29.305Z",
    "updatedAt": "2023-04-24T15:16:29.305Z"
  },
  "isConnected": false,
  "invitationUrl": "https://api.getportabl.com/connect?_oob=eyJib2R5Ijp7ImFjY2VwdCI6WyJkaWRjb21tL3YyIl0sImdvYWxfY29kZSI6IlN5bmMiLCJnb2FsIjoiU3luYyIsInNlcnZpY2VzIjpbeyJpZCI6ImRpZDprZXk6ejZNa3RzRnlINkZxdTRtZGhvdktvSFE5akFrSkpoZFBkQVRrNEVRR0d0OGVpR3EyI0RJRENvbW1NZXNzYWdpbmciLCJ0eXBlIjoiRElEQ29tbU1lc3NhZ2luZyIsInNlcnZpY2VFbmRwb2ludCI6Imh0dHBzOi8vcG9ydGFibC1iZW4tYXBpLm5ncm9rLmlvL2FwaS92MS9hZ2VudC9wcm92aWRlci1hNWU5OGIwYS00MjAxLTQ4MDYtYjQ5Ni1iNWY3ZWQwNzRiNzQvZGlkLWNvbW0iLCJyZWNpcGllbnRLZXlzIjpbImRpZDprZXk6ejZNa3RzRnlINkZxdTRtZGhvdktvSFE5akFrSkpoZFBkQVRrNEVRR0d0OGVpR3EyI3o2TFNoNXBGdlJvRlZ4UTRDeUZqQWt5OUh5RFdKWnpCb2Y5d2gybTg1WVhWRFU3ZyJdfV19LCJpZCI6ImFkZDA0YTk3LTE2MWItNDQ4YS05Yjg5LTEwYWU1YjIyMGMyNiIsInR5cCI6ImFwcGxpY2F0aW9uL2RpZGNvbW0tcGxhaW4ranNvbiIsInR5cGUiOiJodHRwczovL2RpZGNvbW0ub3JnL291dC1vZi1iYW5kLzIuMC9pbnZpdGF0aW9uIiwiZnJvbSI6ImRpZDprZXk6ejZNa3RzRnlINkZxdTRtZGhvdktvSFE5akFrSkpoZFBkQVRrNEVRR0d0OGVpR3EyIiwidGhpZCI6ImFkZDA0YTk3LTE2MWItNDQ4YS05Yjg5LTEwYWU1YjIyMGMyNiIsImNyZWF0ZWRfdGltZSI6MTY4MjM0OTM5MCwiZXhwaXJlc190aW1lIjoxNjgyMzQ5NDUwfQ"
}

Start Sync

Start the sync session which begins the process arround issuance and credential creation.

POSThttps://api.ngrok.io/api/v1provider/sync-sessions/:sync-session-id/start
curl -X POST "https://api.ngrok.io/api/v1provider/sync-sessions/:sync-session-id/start" / 
-H "Authorization: Bearer <TOKEN>"
RESPONSE
202
🚀 QuickstartTerminology