PrivyID API Documentation v1.9

[PRIVYID] API Documentation
v1.9
No. Form:
PRIVY IDENTITAS DIGITAL 001/API/IT/PID/XI/2018
Jl. Kemang Raya No. 15 C, Lantai 4, Bangka, Mampang Prapatan, Revision: 01

Jakarta Selatan 12730
021 22715509 | assist@privy.id | www.privy.id Date: 01 February 2019
PrivyID API Documentation v1.9 Restricted Document

No : 1612201802
Date : 16-Dec-2018
Document History
Date Document Version Description
December 16, 2018 1.0 General API Documentation

February 12, 2019 1.1 Re-edit responses and edit writing method
March 22, 2019 1.2 Add parameter identity, change participant to
recipient, deleting userid parameter
April 8, 2019 1.3 Update endpoint on Production and update
response for check registration status on waiting
April 10, 2019 1.4 • Update Response for Registration on Blank / Invalid
identity NIK (Page 3)
• Add Response for Registration blank or invalid
identity Nama. (Page 4)
• Add Response for Registration Status Blank User
token. (Page 8)
• Update Response for Upload document Blank
owner’s privyId. (Page 12)
April 25, 2019 1.5 • Add info URL download on response API Check
Status Document
• Added Note on Upload document response with
example (Page 11)
May 20, 2019 1.6 • Update description for identity parameter (Page 3)
• Update notes on Upload document (Page 10)
May 31, 2019 1.7 • Update table of contents
• Update signing setup (Page 18)
No. Form:


No : 1612201802
Date : 16-Dec-2018
July 2, 2019 1.8 • Update invalid response and update user status
description (page 7 & 8)
August 6, 2019 1.9 • Adding API Update Data (page 21-27)
No. Form:


No : 1612201802
Date : 16-Dec-2018
Table of Contents
Request Information................................................................................................................... 1
API Reference............................................................................................................................ 2
1. Registration ............................................................................................................................ 2
2. Check Registration Status ..................................................................................................... 6
3. Upload Document ................................................................................................................ 11
4. Check Document Status ...................................................................................................... 16
5. Signing setup ....................................................................................................................... 19
6. API Update Data .................................................................................................................. 21
No. Form:


No : 1612201802
Date : 16-Dec-2018
Request Information
Endpoint
Development https://api-sandbox.privy.id/v3/merchant
Production https://core.privy.id/v3/merchant
Authentication :
Please ask your BusDev associate to contact PrivyID technical team to create account with
merchant key, username and password for accessing API PrivyID.
Header of Request
Parameter’s name Description Required
Merchant-Key Merchant Unique Key Yes
Content-Type form-data Yes
Postman Collection
http://bit.ly/PrivyAPI
1
No. Form:


No : 1612201802
Date : 16-Dec-2018
API Reference
1. Registration
REQUEST
POST /registration
BODY OF REQUEST
Parameter’s Type Example Description
name
email* String user@usermail.com User’s email
phone* String 08233324223 User’s phone number
selfie* File ExampleSelfie.png Face close up photo of Registrant
on image format (.png/ .jpg/ .jpeg)
ktp* File ExampleKTP.png User’s identity card on image
format (.png/ .jpg/ .jpeg)
identity* Object[] {"nik": Registrant’s identity. NIK, name and
"1234123412341234", date of birth required. NIK must be
"nama":"Test", 16 digits and 16th digits can’t be 0
"tanggalLahir":"1989-11-
01"}
* : Required
RESPONSE PARAMETER
Parameter’s name Type Description
code String HTTP Status Code

data Object[] User’s information
email String User’s email
phone String User’s phone
userToken String User’s random token generated from Privy system
status String User’s status. Value : waiting

message String Message of response
2
No. Form:


No : 1612201802
Date : 16-Dec-2018
Response
1. Success
{
"code": 201,
"data": {
"email": "mail@example.com",
"phone": "+62834988803591",
"userToken":
"0316a5332d05e5eb86a93ce13608252753e7f2b808c7e5739d8cb340a62acd9d",
"status": "waiting"
},
"message": "Waiting for Verification"
}
2. Blank or invalid email/phone/ktp/selfie

{
"code": 422,
"errors": [
{
"field": "email",
"messages": [
"is required",
"cannot be blank",
"is invalid",
]
}
],
"message": "Validation(s) Error"
}
3. Blank or Invalid Identity NIK

{
"code": 422,
"errors": [
{
"field": "identity.nik",
"messages": [
"cannot be blank",
"NIK must be 16 digit number",
]
}
],
}
3
No. Form:


No : 1612201802
Date : 16-Dec-2018
4. Blank or Invalid Identity Nama
{
"code": 422,
"errors": [
{
"field": "identity.nama",
"messages": [
"is too short (minimum is 3 characters)",
]
}
],
}
5. Invalid format of KTP and Selfie
{
"code": 422,
"errors": [
{
"field": "selfie",
"messages": [
"file must be image jpg or png"
]
}
],
}
6. Already register but still in a verification process
{
"code": 422,
"errors": [
{
"field": "email",
"messages": [
"Email blackparad199e@dsfa.com has been registered, is
still a verification process"
]
},
{
"field": "phone",
"messages": [
"Phone +62834921303591 has been registered, is still a
verification process"
]
}
4
No. Form:


No : 1612201802
Date : 16-Dec-2018
],
}
7. Registered phone or email
{
"code": 422,
"errors": [
{
"field": "phone",
"messages": [
"Phone +62898321303511 already registered"
]
}
],
5
No. Form:


No : 1612201802
Date : 16-Dec-2018
2. Check Registration Status

REQUEST
POST /registration/status
BODY OF REQUEST
name
token* String bec11d7ff1e1d592133745fbb7d166eefcfb376b User’s token from
24bd349eb9666b37a341599e Registration API
* : Required
RESPONSE PARAMETER

data Object[] User’s information
email String User’s email
phone String User’s phone
data Object[]
privyId String User’s PrivyID
userToken String User’s random token generated from Privy system
status String User’s status. Value : waiting, invalid, rejected, verified,

registered
identity Object[] User’s identity based on his/her ID Card
nama String User’s name
nik String User’s identity number
tanggalLahir String User’s birthdate
tempatLahir String User’s birthplace
6
No. Form:


No : 1612201802
Date : 16-Dec-2018
Note :
User Status
1. Waiting : user is waiting to be verified
2. Invalid : user is rejected by privy and can be verified if user sends supporting data
3. Rejected : user is rejected by privy and cannot be verified again, because the
document sent does not meet the requirements. User need to register again with
another document or another identity card.
Example reason with rejected status : identity card can be found on the internet, ID
number on identity card and supporting document (family card) not found.
4. Verified : user has been successfully verified by privy
5. Registered : user has been registered on privy
Response
1. Success – waiting
{
"code": 201,
"data": {
"email": "heheh@hoho.com",
"phone": "+62856437684663",
"userToken":
"d37e052e49fb69d2795fd83d31817176aa495b02a3271127d01dcdf135c1a53a",
"status": "waiting"
},
"message": "Waiting for Verification"
}
2. Success – rejected
{
"code": 201,
"data": {
"privyId": null,
"email": "rcktdy@gmail.com",
"phone": "+62877920062111",
"processedAt": "2019-06-24 14:45:58 +0700",
7
No. Form:


No : 1612201802
Date : 16-Dec-2018
"userToken":
"ab7d7ff16599e09ddf63b492a0db68ac8e0e4e015e584c318a8472faad4cee87",
"status": "rejected",
"reject": {
"code": "PRVM001",
"reason": "Email telah terdaftar dengan NIK yang berbeda",
"handlers": []
}
},
"message": "Data Rejected"
}
3. Success – verified
{
"code": 201,
"data": {
"privyId": "JO6663",
"email": "mail@example8s.com",
"phone": "+62856437006663",
"processedAt": "2019-04-19 20:02:06 +0700",
"userToken":
"fa3c4afdce0b48ea63f8e648f296c8ff6db41d93976d994a94329390d88dcaa5",
"status": "verified",
"identity": {
"nama": "Jon Snow",
"nik": "1234567890123969",
"tanggalLahir": "1993-02-02",
"tempatLahir": "Salakan"
}
},
"message": "Data Verified"
}
4. Success – registered
{
"code": 201,
"data": {
"privyId": "JO6663",
"email": "newmail@exampl8s.com",
"phone": "+62856437009663",
"processedAt": "2019-04-19 20:09:03 +0700",
"userToken":
"f89341b462ec9a61308e8aca333373a479988a6957da1f06c606af6fa222f8d7",
"status": "registered",
"identity": {
"nama": "Jon Snow",
"nik": "1234567890123969",
8
No. Form:


No : 1612201802
Date : 16-Dec-2018
"tanggalLahir": "1993-02-02",
"tempatLahir": "Salakan"
}
},
"message": "Data has been Registered"
}
5. Success – Invalid
{
"code": 201,
"data": {
"privyId": null,
"email": "ikviaulias@gmail.czo",
"phone": "+62856426209077",
"processedAt": "2019-06-26 15:50:03 +0700",
"userToken":
"a8141b5d314be770da6c958610ed6d3aedb001880e1c58de7ef526173c12e65b",
"status": "invalid",
"reject": {
"code": "PRVK002",
"reason": "Foto KTP yang diunggah tidak dapat terbaca (mis.
gambar kabur, kecil, dll.)",
"handlers": [
{
"category": "KTP",
"handler": "Foto KTP/Resi e-KTP/e-KTP Asli",
"file_support": []
}
]
}
},
}
6. Invalid User Token
{
"code": 404,
"errors": [],
"message" : "Unable to find userToken wR0nGuS3rT0kEn"
}
9
No. Form:


No : 1612201802
Date : 16-Dec-2018
7. Blank userToken
{
{
"code": 422,
"errors": [
{
"field" : "token",
"messages" : [
"cannot be blank"
]
}
],
"message": "Validation(s) Error”
}
10
No. Form:


No : 1612201802
Date : 16-Dec-2018
3. Upload Document
REQUEST
POST /document/upload
BODY OF REQUEST
name
documentTitle* String Example Title Document title
docType* String Serial Document workflow. Value :
Serial, Parallel
owner* String { Document owner. Contains
"privyId":"AB1234", privyId and enterpriseToken,
"enterpriseToken": enterpriseToken on example
"41bc84b42c8543daf448d893c2
column can be used for
55be1dbdcc722e"
} Development Environment.
Every merchant has their own
enterpriseToken and use them
in Production Environment.
document* File Exampledoc.pdf Document with pdf format.
recipients* Object[] [ Recipients list.
{ Type can be : Signer, Reviewer.
"privyId":"TES001", If the document type is Serial,
the signing or reviewing process
"type":"Reviewer","enterpri will be based on the order of
seToken": "companytoken"
recipients.
},{
"privyId":"TES002",
"type":"Signer","enterprise
Token": ""
}
]
* : Required
Notes :
1. “enterpriseToken” in parameter recipients refer to user’s EnterpriseID account token which
can be acquired by registering user’s Company.
2. Document workflow :
- Serial : the signing or reviewing process will be based on the order of recipients
- Parallel : signer or reviewer can sign the document without having to wait for a previous one
11
No. Form:


No : 1612201802
Date : 16-Dec-2018
RESPONSE PARAMETER

data Object[]
docToken String Document token, generated by Privy system
urlDocument String Document link to sign or view
recipients Object[] Recipients list
privyId String User’s privyId
type String Recipient’s role on the document (Signer and Reviewer),
case sensitive.
enterpriseToken String Merchant’s token

Note :
• Merchant can add autofill PrivyID to the document URL that will be given to the user
(https://sign-sandbox.privy.id/{docToken}?privyId=ME1234)
example :
urlDocument : https://sign-
sandbox.privy.id/61c29277d95c3d06aa80617f60a8f2fa11e3a3a7a63ce431070493a931ecb7a8?p
rivyId=ME1234
Response
1. Success
{
"code": 201,
"data": {
"docToken":
"61c29277d95c3d06aa80617f60a8f2fa11e3a3a7a63ce431070493a931ecb7a8",
"urlDocument": "https://sign-
sandbox.privy.id/61c29277d95c3d06aa80617f60a8f2fa11e3a3a7a63ce431070493a931
ecb7a8",
"recipients": [
{
"privyId": "KE8226",
"type": "Reviewer",
"enterpriseToken": null
},
{
"privyId": "TES002",
12
No. Form:


No : 1612201802
Date : 16-Dec-2018
"type": "Signer",
"enterpriseToken": null
}
]
},
"message": "Document successfully upload and shared"
}
2. Invalid format of document
{
"code": 422,
"errors": [
{
"field": "document",
"messages": [
"file must be pdf"
]
}
],
}
3. Invalid PrivyID
{
"code": 422,
"errors": [
{
"field": "recipients.0.privyId",
"messages": [
"privyId AI7277 not found"
]
}
],
}
4. Invalid type on recipient list
{
"code": 422,
"errors": [
{
"field": "recipients.0.type",
"messages": [
"Only fill with Signer or Reviewer"
]
}
13
No. Form:


No : 1612201802
Date : 16-Dec-2018
],
}
5. Owner PrivyID didn't registered in that enterprise
{
"code": 422,
"errors": [
{
"field": "owner.privyId",
"messages": [
"privyId TXS001 not found"
]
}
],
"messages": “Validation(s) Error”
}
6. Invalid enterprise token
{
"code": 422,
"errors": [
{
"field": "owner.enterpriseToken",
"messages": [
"Invalid EnterpriseToken"
]
}
],
}
14
No. Form:


No : 1612201802
Date : 16-Dec-2018
7. Blank enterprise token
{
"code": 422,
"errors": [
{
"field": "owner.enterpriseToken",
"messages": [
"cannot be blank"
]
}
],
}
8. Blank Owner’s privyId
{
"code": 422,
"errors": [
{
"field": "owner.privyId",
"messages": [
"cannot be blank",
"privyId not found",
]
}
],
}
15
No. Form:


No : 1612201802
Date : 16-Dec-2018
4. Check Document Status

REQUEST
GET /document/status/:docToken
PARAMS REQUEST
name
docToken* String e9749bef897b0594c16d63f61fdab00c264cae27 Document token
b2919241dc04f1331b47dc44 from Upload API
* : Required
RESPONSE PARAMETER

data Object[] Document token, generated by Privy system
docToken String Link to sign document
documentStatus String Document status. Value : Completed, In Progress
urlDocument String Link to view or download original and signed document
recipients Object[] Recipient list
privyId String User’s privyId
type String Recipient’s role on the document (Signer and Reviewer)
signatoryStatus String Recipient’s status. Value : Completed, In Progress
download Object[] download can be used if documentStatus: completed or all

recipient has signed / reviewed
url String The url is valid for 15 minutes. If it's already expired, it can
hit API again
expiredAt String url validity time
16
No. Form:


No : 1612201802
Date : 16-Dec-2018
Response
1. Success – Completed Document
{
"code": 200,
"data": {
"docToken":
"bb5e12c77438f60da1f2ab6e566c5aeb6d03561bec3e5d588f7e240e4c164120",
"recipients": [
{
"privyId": "AB1234",
"type": "Reviewer",
"signatoryStatus": "Completed"
},
{
"privyId": "DE3456",
"type": "Signer",
}
],
"documentStatus": "Completed",
"urlDocument": https://sign-
sandbox.privy.id/doc/bb5e12c77438f60da1f2ab6e566c5aeb6d03561bec3e5d588f7e24
0e4c164120,
"download": {
"url": "http://api-sandbox.privy.id/document/6S7p0MVgdB-
f9a360ab-6d47-41d8-881d-b4492bad49f8",
"expiredAt": "2019-04-25T09:33:58+00:00"
}
},
"message": "Successfully get a status document"
}
17
No. Form:


No : 1612201802
Date : 16-Dec-2018
2. Success – Document In progress
{
"code": 200,
"data": {
"docToken":
"bb5e12c77438f60da1f2ab6e566c5aeb6d03561bec3e5d588f7e240e4c164120",
"recipients": [
{
"privyId": "AB1234",
"type": "Reviewer",
},
{
"privyId": "DE2345",
"type": "Signer",
"signatoryStatus": "In Progress"
}
],
"documentStatus": "In Progress",
"urlDocument": "https://sign-
sandbox.privy.id/doc/bb5e12c77438f60da1f2ab6e566c5aeb6d03561bec3e5d588f7e24
0e4c164120"
},
"message": "Successfully get a status document"
}
3. Invalid document token
{
"code": 404,
"errors": [],
"message": "Unable to find docToken 123445555"
}
18
No. Form:


No : 1612201802
Date : 16-Dec-2018
5. Signing setup
On this section, merchants can setup :
• Redirect after a successful sign
• Specific coordinate
• Specific page
With the following details :
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<title>Document</title>
</head>
<body>
<div class="privy-document"></div>
<script src="https://unpkg.com/privy-sdk@next"></script>
<script>
Privy.openDoc('4e0f4cd87346e8ebfcb9dca0415183f0c99dd0ea6c90b4fc2f0508069
17146d4', {
dev: true,
container: '.privy-document',
privyId : '', //Autofill privyID
signature: {
page: 11,
x: 130,
y: 468,
fixed: false
}
}).on('after-action', (data) => {
location.href = '//www.google.com' //After sign/review doc
})
.on('after-sign', (data) => { //After sign doc
location.href = '//www.aftersign.com'
})
.on('after-review', (data) => { //After review doc
location.href = '//www.afterreview.com'
})
</script>
</body>
</html>
</html>
19
No. Form:


No : 1612201802
Date : 16-Dec-2018
Notes :
1. Insert acquired token after upload document with API on :
Privy.openDoc (‘tokenDocument’).
2. Environment configuration :
• dev : true, document and redirect URL on environment sandbox.
• dev : false. Document and redirect URL on environment production.
3. “privyId” fill with user privyid if merchant want to auto fill privyID when login
4. Signature (optional), to automatically set signature position after user login.
• Page, page to be signed
• x, y. signature coordinate.
• Fixed, if “true”, signature can’t be moved and if “false”, user still can move the signature on the
desired place.
5. Redirect page:
• On (after-action), redirect URL after signing or reviewing process completed.
• On (after-sign), after sign completed, if merchant want to specifically differentiate for
sign only
• On (after-review), after review completed, if merchant want to specifically differentiate
for reviewing document only
20
No. Form:


No : 1612201802
Date : 16-Dec-2018
6. API Update Data

On this section, merchant can resend file support if user’s status is invalid, for example, this
is a payload response API check registration status :
{
"code": 201,
"data": {
"privyId": null,
"email": "alexanderwarsono@gmail.czo",
"phone": "+62856426209077",
"processedAt": "2019-06-26 15:50:03 +0700",
"userToken":
"a8141b5d314be770da6c958610ed6d3aedb001880e1c58de7ef526173c12e65b",
"status": "invalid",
"reject": {
"code": "PRVK002",
"reason": "Foto KTP yang diunggah tidak dapat terbaca (mis.
gambar kabur, kecil, dll.)",
"handlers": [
{
"category": "KTP",
"handler": "Foto KTP/Resi e-KTP/e-KTP Asli",
"file_support": []
}
]
}
},
}
Notes :
1. On “handler” parameter, there is an information about file support that need to be sent by
merchant, on the example above, merchant must upload identity card file (KTP).
2. “category” shows API that need to be called
3. There are 3 URL with 3 different ID category (ktp, selfie, fileSupport), the category refers to
“category” parameter.
21
No. Form:


No : 1612201802
Date : 16-Dec-2018
REQUEST
POST /user/merchant/reregister/:category
HEADER OF REQUEST
Parameter’s name Description Required
Token User’s Registration Token Yes
Merchant-Key Merchant Unique Key Yes
BODY OF REQUEST
name
ktp* File Fotoktp.jpg On this API, merchant can
update User’s Identity card
photo (KTP).

name
selfie* File Fotoselfie.jpg On this API, merchant can
update User’s Selfie photo.

name
fileSupport* String FotoKK.jpg On this API, merchant can
update User’s data with
supporting file.
22
No. Form:


No : 1612201802
Date : 16-Dec-2018
EXAMPLE REQUEST
1. Category : KTP
23
No. Form:


No : 1612201802
Date : 16-Dec-2018
2. Category : Selfie
3. Category : fileSupport
24
No. Form:


No : 1612201802
Date : 16-Dec-2018
Example of invalid status and user have to send file support : SIM
Payload of User Status :
{
"eventName": "register",
"data": {
"privyId": null,
"email": "kendall@jenner.comssgg",
"phone": "+6287800023389",
"processedAt": "2019-08-14 12:54:31 +0700",
"userToken":
"7ee02215aa269cf83b1528a8f76afeba0d3749e8d3fa15d72ef76064cf4c9917"
"reject": {
"code": "PRVK006",
"reason": "Foto wajah pada KTP tidak jelas",
"handlers": [
{
"category": "FILE-SUPPORT",
"handler": "Foto SIM",
"file_support": [
"SIM"
]
}
]
}
},
}
25
No. Form:


No : 1612201802
Date : 16-Dec-2018
Then, merchant need to call API with category “file-support”, with payload :
RESPONSE PARAMETER

data String Empty string, value : null
errors String Empty string, value : []
Response
1. Success – Update ID Card
{
"code": 201,
"data": null,
"message": "Successfully upload ID Card"
}
2. Success – Update Selfie
{
"code": 201,
"data": null,
"message": "Successfully upload Selfie"
}
26
No. Form:


No : 1612201802
Date : 16-Dec-2018
3. Success – Registering with Supporting file
{
"code": 201,
"data": null,
"message": "Registration has been successful"
}
4. User is not rejected/invalid
{
"code": 403,
"errors": [],
"message": "Registration is not rejected."
}
5. Invalid reregister (Using wrong reregister)
{
"code": 403,
"errors": [],
"message": "Registration is not rejected."
}
6. Invalid fileSupport Category (Only SIM/KK/PASSPORT/FILE-SUPPORT is accepted,

based on the invalid reason)
{
"code": 422,
"errors": [
{
"field": 0,
"messages": [
"category for this user is not accepted. Category accepted
are / is SIM"
]
}
],
}
27

PrivyID API Documentation v1.9

Uploaded by

Copyright:

Available Formats

PrivyID API Documentation v1.9

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

PrivyID API Documentation v1.9

Uploaded by

Copyright:

Available Formats

[PRIVYID] API Documentation

Jl. Kemang Raya No. 15 C, Lantai 4, Bangka, Mampang Prapatan, Revision: 01