Signzy Video Personal Discussion – Integration Specification





Purpose:

This document describes the Signzy Video PD (Video Personal Discussion) APIs that are to be consumed for integrating the Video PD journey into a third-party system (for example, Salesforce or a Loan Origination System). The integration flow, request and response contracts remain identical irrespective of the calling system.



APIs:

The below Signzy APIs are to be used, in the sequence given:



Base URL

https://videopd-demo.signzy.app

Portal Access (Demo Environment)



Note: The above are demo-environment credentials only. Production credentials and the production base URL will be shared separately over a secure channel (1:1).



Before You Start — Rate Limits

The Agent Login endpoint is throttled. Exceeding any of the limits below returns HTTP 429 with the remaining wait time.



Cache the agent token for its full lifetime and reuse it across calls; do not log in before every Create Call or Follow-up Call request — a per-request login loop will exhaust these limits and lock the integration out for 30 minutes.



Two-Factor Authentication

If the agent account has requires2FA set to true, the agent portal (UI) will prompt for an OTP on login. This does not affect the API: the token returned by the Agent Login API is issued and fully usable regardless of the requires2FA value. It is recommended to use an agent account with 2FA disabled for the integration.



Token Lifetime

The 24-hour default applies to both the agent token and the auditor portal token, and both are configurable per environment. The participant’s joining link is not.



Note: there is currently no token revocation or refresh mechanism. Extending the lifetime enlarges the exposure window of a bearer token that cannot be revoked; if the goal is simply to avoid frequent logins, caching the token for its existing 24-hour lifetime (see Rate Limits above) is the safer fix.





This API authenticates the agent and returns a JWT bearer token, already prefixed with "Bearer ". The token returned here must be passed in the Authorization header of the Create Call and Follow-up Call APIs exactly as received.



Endpoint

POST  https://videopd-demo.signzy.app/backend/agent/login



Headers



Request –



Response –

The response returns the agent profile along with the token. The token payload contains the agentId, auditorId, email and role, and carries an expiry (exp) claim — the default validity is 24 hours from the time of issue, but this can be configured based on requirement.

Agent Login cURL



This API schedules a new Video PD call for one or more participants. On success it returns a session object (HTTP 201) containing session.sessionId, which must be retained by the calling system as it is required to raise a follow-up call against the same case.



Endpoint

POST  https://videopd-demo.signzy.app/backend/session/create



Headers



Request –

Up to four participants can be added in the array above — the agent portal supports four per call, but the API does not enforce a hard limit; cap the count on your side.





Note: identifier must be unique across every Video PD call. Creating a second call with an identifier that already exists is rejected — treat this as "this case already has a Video PD call" and look up the existing one rather than retrying with the same value. The same identifier must also be passed again while raising a follow-up call, so that the follow-up is linked to the correct Video PD case. Unrecognised body fields are silently dropped, not rejected — a misspelled field will not error, it will simply be missing from the created call.



Response –

The record is returned nested under session. Remaining bookkeeping fields inside it (_id, createdAt, updatedAt, participants[]._id, etc.) can be ignored by the integration.



Create Call cURL

This API schedules a follow-up call against an existing Video PD session. The session ID returned by the Create Call API is appended to the URL, and the same identifier used at the time of creation must be passed in the request body so that the follow-up is mapped to the correct case.



Endpoint

POST  https://videopd-demo.signzy.app/backend/session/follow-up/{sessionId}

Path Parameter



Headers



Request –





Response –

The follow-up is created as a new call with its own session.sessionId; the parent call’s applicationStatus flips to "follow-up scheduled".



Follow-up Call cURL



Every error follows the same shape:





The cURL requests given above are to be set up and executed in the following sequence.



Step 1: Import all three cURL requests (Agent Login, Create Call, Follow-up Call) into Postman as a single collection.

Step 2: Trigger the Agent Login cURL by providing the agent username and password. Demo credentials are given in the Portal Access section above; production credentials will be shared separately over a secure channel.

Step 3: Copy the token returned in the Agent Login response. Its default validity is 24 hours, but this can be configured based on requirement.

Step 4: Set the token value as the Authorization header of the Create Call cURL exactly as returned — it already includes the Bearer prefix, so do not add the word Bearer yourself. The placeholder <AGENT_ACCESS_TOKEN> in the cURL is to be replaced with this value. Cache the token for its lifetime; do not call Agent Login before every Create Call or Follow-up Call request.

Step 5: Trigger the Create Call cURL with the required scheduling details — title, date, startTime, endTime, participant details (name, email, mobile and scheduled location) and the case identifier. The agent portal supports up to four participants per call; the API itself does not enforce this as a hard limit.

Step 6: From the Create Call response, note session.sessionId and retain it against the case in the calling system (Salesforce / LOS). The scheduled call will now be visible on the agent dashboard. The participant will receive the joining link by email always, and by SMS only where SMS invitations are enabled for that environment — both are best-effort, so a 201 response is not proof the participant was reached.

Step 7: To raise a follow-up, append the parent’s session.sessionId received in Step 6 to the Follow-up Call URL, and add the same agent bearer token in the Authorization header.

Step 8: In the Follow-up Call request body, pass the same identifier used in the Create Call request — it is mandatory and must match exactly, or the follow-up is rejected — along with the optional questionnaireId, so that the follow-up is linked to the correct Video PD case. Then trigger the request.

Step 9: Log in to the Auditor portal using the auditor credentials to review the completed Video PD sessions and their recordings.



Sequence Summary