Skip to main content

​
About Persona

Persona is an identity verification and compliance platform used for KYC and KYB checks and fraud prevention. The Serval integration connects to your Persona organization with an API key and gives workflows on-demand access to the entire Persona API through a single “Persona API request” action. The key is only ever sent to Persona’s official API address (api.withpersona.com), and Serval pins Persona API version 2025-10-27 on every request, so workflow behavior stays consistent regardless of your key’s default version. Authentication: API key (created in the Persona Dashboard) Data sync: On demand only - no background sync, no scheduled imports, and no pre-installed workflows. Persona is called only when a workflow runs the “Persona API request” action.

​
What the Persona integration enables

Anything defined in the Persona API can be accessed through Serval.

​
Get your credentials

You need an organization API key from the Persona Dashboard. Sandbox keys start with persona_sandbox and production keys start with persona_production. For background, see the Persona API reference.
1

Sign in to the Persona Dashboard

Go to the Persona Dashboard and sign in.
2

Open API Keys

Navigate to API, then API Keys.
3

Create the key

Click Create API key. When asked for the API version, select 2025-10-27 - Serval sends this version on every request (see Persona API versioning), so choosing it keeps your key’s settings aligned with what workflows actually see.
Persona API keys have full permissions until you explicitly configure restrictions. Consider restricting the key to only what your workflows need.
4

Copy the key immediately

Persona shows the full key only once. Copy it right away - if you lose it, you will need to create a new key.
Sandbox and production are separate keys, not separate settings. If you use both environments, create one key per environment and connect each one to Serval as its own connection.

​
Connect in Serval

1

Open the Persona connect form

In Serval, open the Persona integration and start a new connection. The Configure Persona dialog opens with two fields.
2

Enter an Instance Name

A friendly display name for the connection. The helper text reads: “A friendly name for this Persona integration (e.g., ‘Production’, ‘Staging’)”. Leaving it blank shows “This field is required”.
3

Enter your API Key

Paste the full key you copied from the Persona Dashboard. It is a password field, so the value is hidden as you type. The helper text reads: “Your Persona API key (starts with persona_sandbox or persona_production)”. The field is marked with an asterisk, but the form does not actually block saving when it is left blank - paste carefully.
4

Submit the form

Click Submit. Serval does not test the key when you save - a mistyped, blank, or revoked key is only caught the first time a workflow calls Persona. If the save itself fails you will see a general error such as “Failed to install integration”. After saving, the key is shown masked - bullet characters plus its last 4 characters - and can be replaced later but never viewed in full.
When editing an existing Persona connection - even just to rename it - always replace the API key in the same save: select the pencil icon (or Replace button) next to the masked value, paste the complete API key, keep the Instance Name filled in, and save in one step. Do not save while the key field is blank or still showing only its masked value. After saving, run a workflow that calls Persona to confirm the connection still works. Follow the same routine when rotating the key.

​
Verifying the connection

This integration has no built-in health checks, and the key is not validated when you connect. To verify the connection, run a workflow that uses the “Persona API request” action - for example, one that lists recent inquiries - and confirm it returns data. An invalid or revoked key shows up as a failed request - typically an authorization error from Persona.
If requests succeed but you cannot find the records you expect, check which environment the key belongs to: keys starting with persona_sandbox only see sandbox data, and keys starting with persona_production only see production data. The Instance Name is just a label - the key determines the environment.

​
Gotchas and troubleshooting

Saving the edit form without re-entering the API key can break the connection. Whenever you edit a Persona connection - even just to rename it - select the pencil icon (or Replace button) next to the masked key, paste the complete API key, save, and then run a workflow call to confirm it still works. Errors during the edit itself appear as “Failed to update configuration”.
Serval does not test the key at connect time and runs no recurring health checks, so a wrong, restricted, or revoked key surfaces only when a workflow’s Persona API request fails (typically with an authorization error from Persona). If you suspect the key, create a fresh one in the Persona Dashboard and replace it in Serval. The Persona Help Center covers managing keys on the Persona side.
Every request Serval sends uses Persona API version 2025-10-27, overriding the key’s default version. Request and response shapes in workflows follow that version - see Persona API versioning if your team relies on a different version elsewhere.
Both environments are reached the same way - only the key (its persona_sandbox or persona_production prefix) determines which environment a connection talks to. Use the Instance Name to label the environment clearly, and connect sandbox and production as separate connections.
Persona wraps every record in a standard envelope: the useful fields live under data.attributes, not at the top level, and lists come back as a data array. If a workflow builder reports “missing” fields, this nesting is the usual cause.
Serval attaches your API key only to requests going to api.withpersona.com. The Persona API request action targets that address automatically, and the credential is never sent anywhere else.
Need help? Contact support@serval.com for assistance with your Persona integration.