VideoPD APIs

video pd api signzy video personal discussion – integration specification prepared by signzy team creation date 15 september 2026 last updated 16 september 2026 document version 1 1 0 environment demo / pre production 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 agent login api – generates the bearer token used to authorise the subsequent calls create call api – schedules a new video pd call and returns the session id follow up call api – schedules a follow up call against an already created session base url https //videopd demo signzy app portal access (demo environment) role portal url username password agent https //videopd demo signzy app/agent/login xxxxx yyyyyy auditor https //videopd demo signzy app/auditor/login wwww zzzzzz 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 limit threshold window failed logins per account 5 30 minutes failed logins per ip address 10 30 minutes total requests per ip address 50 30 minutes 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 token default lifetime configurable agent api token (this document) 24 hours yes auditor portal token 24 hours yes participant joining link 24 hours no 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 1\ agent login api 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 header value mandatory content type application/json y request – { "username" "xxxx", "password" "yyyyy" } field name sample data type mandatory username xxxxx string y password yyyyy string y 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 { " id" "6948acba636e214f44f43a45", "username" "\<agent username>", "name" "agent name", "email" "agent\@example com", "companyname" "example financial services", "requires2fa" false, "token" "bearer eyjhbgcioijiuzi1niisinr5cci6ikpxvcj9 \<payload> \<signature>" } field name description type id unique internal identifier of the agent record string username login username of the authenticated agent string name full name of the agent string email registered email address of the agent string companyname name of the company / organisation the agent is associated with string requires2fa whether 2fa is enabled for this agent on the portal does not affect api token usability boolean token jwt bearer token, already prefixed with "bearer ", to be used in the authorization header of all subsequent video pd api calls exactly as returned default validity 24 hours, configurable string agent login curl curl location 'https //videopd demo signzy app/backend/agent/login' \\ \ header 'content type application/json' \\ \ data raw '{ "username" "xxxxx", "password" "yyyyy" }' 2\ create call api 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 header value mandatory content type application/json y accept application/json n authorization bearer \<agent access token> (token from the agent login api, used exactly as returned) y request – { "title" "title6", "date" "2026 10 08t00 00 00 000z", "starttime" "2026 10 08t10 30 00 000z", "endtime" "2026 10 08t11 00 00 000z", "participants" \[ { "name" "sample user", "email" "sample\@xyz com", "mobile" "9876543210", "scheduledlocation" { "address" "xyz, 560078", "latitude" 12 8978624, "longitude" 77 58450839999999 } } ], "identifier" "4471982", "questionnaireid" "6948ae1c636e214f44f4xxxx", "location" { "address" "xyz, 560078", "latitude" 12 8978624, "longitude" 77 58450839999999 } } 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 field name description type mandatory title title/label for the video pd call string y date date on which the call is being scheduled (iso 8601, utc) string y starttime scheduled start time of the call (iso 8601, utc) string y endtime scheduled end time of the call (iso 8601, utc) string y participants array of participant objects the agent portal supports up to four per call; the api itself does not enforce this cap array y participants\[] name full name of the call participant string y participants\[] email email address of the call participant must be a valid email — it is format validated and receives the joining link string y participants\[] mobile mobile number of the call participant must be a valid indian mobile number — 10 digits starting 6–9, optionally prefixed +91 string y participants\[] scheduledlocation location at which the participant is expected to join the call object n address address text for the participant’s location string n latitude latitude of the participant’s location number n longitude longitude of the participant’s location number n identifier caller’s own unique reference for this case (e g los application number) must be unique across every video pd call string y questionnaireid id of the questionnaire (use case configured in auditor portal) to run during the call ids come from get /backend/questionnaire/use cases/agent string n location call level location, same shape as scheduledlocation object n 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 201 created { "session" { "sessionid" "01kpqfy68t4zs0cy78jnp8xxxx", "title" "title6", "date" "2026 10 08t00 00 00 000z", "starttime" "2026 10 08t10 30 00 000z", "endtime" "2026 10 08t11 00 00 000z", "identifier" "4471982", "questionnaireid" "6948ae1c636e214f44f4xxxx", "applicationstatus" "incomplete", "isfollowupcall" false, "parentsessionid" null, "participants" \[ { " id" " ", "name" "sample user", "email" "sample\@xyz com", "mobile" "9876543210", "scheduledlocation" { " " " " }, "invitestatus" "pending", "joined" false } ], " id" " ", "createdat" " ", "updatedat" " " } } field name description type session sessionid unique id of the scheduled video pd session to be stored by the calling system and used in the follow up call api url string session identifier echo of the case identifier submitted in the request string create call curl curl location 'https //videopd demo signzy app/backend/session/create' \\ \ header 'content type application/json' \\ \ header 'authorization bearer \<agent access token>' \\ \ data raw '{ "title" "title6", "date" "2026 10 08t00 00 00 000z", "starttime" "2026 10 08t10 30 00 000z", "endtime" "2026 10 08t11 00 00 000z", "participants" \[ { "name" "sample user", "email" "sample\@xyz com", "mobile" "9876543210", "scheduledlocation" { "address" "xyz, 560078", "latitude" 12 8978624, "longitude" 77 58450839999999 } } ], "identifier" "4471982", "questionnaireid" "6948ae1c636e214f44f4xxxx" }' 3\ follow up call api 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 parameter description sample data type mandatory sessionid the parent call’s sessionid — the 26 character ulid returned as session sessionid in the create call response (not the id field alongside it) 01kpqfy68t4zs0cy78jnp8xxxx string y headers header value mandatory content type application/json y accept application/json n authorization bearer \<agent access token> (token from the agent login api, used exactly as returned) y request – { "title" "follow up title6", "date" "2026 10 09t07 45 00 000z", "starttime" "2026 10 09t07 45 00 000z", "endtime" "2026 10 09t08 15 00 000z", "participants" \[ { "name" "sample user", "email" "sample\@xyz com", "mobile" "9876543210", "scheduledlocation" { "address" "xyz, 560078", "latitude" 12 8978624, "longitude" 77 58450839999999 } } ], "identifier" "4471982", "questionnaireid" "6948ae1c636e214f44f4xxxx" } field name description type mandatory title title/label for the follow up call string y date date on which the follow up call is being scheduled (iso 8601, utc) string y starttime scheduled start time of the follow up call (iso 8601, utc) string y endtime scheduled end time of the follow up call (iso 8601, utc) string y participants array of participant objects, same structure and rules as the create call api array y identifier identifier of the original call against which the follow up is being raised must be passed, and must match the identifier used at the time of creation exactly string y questionnaireid id of the questionnaire to be used for the follow up call session defaults to none if omitted string n 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" 201 created { "message" "follow up created", "session" { "sessionid" "01kpqfy68t4zs0cy78jnp8yyyy", "title" "follow up title6", "date" "2026 10 09t07 45 00 000z", "starttime" "2026 10 09t07 45 00 000z", "endtime" "2026 10 09t08 15 00 000z", "identifier" "4471982", "questionnaireid" "6948ae1c636e214f44f4xxxx", "applicationstatus" "incomplete", "isfollowupcall" true, "parentsessionid" "\<parent id>", "participants" \[ " " ], " id" " ", "createdat" " ", "updatedat" " " } } follow up call curl curl location 'https //videopd demo signzy app/backend/session/follow up/01kpqfy68t4zs0cy78jnp8xxxx' \\ \ header 'content type application/json' \\ \ header 'authorization bearer \<agent access token>' \\ \ data raw '{ "title" "follow up title6", "date" "2026 10 09t07 45 00 000z", "starttime" "2026 10 09t07 45 00 000z", "endtime" "2026 10 09t08 15 00 000z", "participants" \[ { "name" "sample user", "email" "sample\@xyz com", "mobile" "9876543210", "scheduledlocation" { "address" "xyz, 560078", "latitude" 12 8978624, "longitude" 77 58450839999999 } } ], "identifier" "4471982", "questionnaireid" "6948ae1c636e214f44f4xxxx" }' error responses every error follows the same shape { "status" "error", "statuscode" 0, "message" " " } status code meaning 400 schema validation failure — invalid mobile number or email format, missing required field 401 bad credentials at login; a doubled or expired authorization token; agent has no linked auditor 403 authenticated, but wrong role for this endpoint 422 addresses could not be geocoded (see geocoding note under create call api) 429 login rate limit exceeded (see before you start — rate limits) 500 currently returned for a duplicate identifier or a follow up identifier mismatch these are user input validation failures, not server errors — do not treat as transient / retryable a fix to return 409 / 400 instead is tracked internally steps to be followed 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 \# api method endpoint auth 1 agent login post /backend/agent/login none (public, rate limited) 2 create call post /backend/session/create bearer token 3 follow up call post /backend/session/follow up/{sessionid} bearer token \<font color="#2166ae">getting help\</font> if you have any questions, need clarification, or have suggestions to enhance our documentation or services, please don't hesitate to contact us reach out to us at help\@signzy com mailto\ help\@signzy com