Search Credentials

Start an academic credentials verification (Transcript, Certificate, or Both). Send multipart/form-data and attach the credential document plus the signed consent document. Flow: if consent is false/omitted → status Pending Consent; if the candidate already has verified records in our catalog → status Complete immediately and results are ready to fetch; otherwise → status Processing (awaiting verification), then poll status until Complete and GET results. Always returns search_id. Call GET /api/v1/credentials/countries for country, then GET /api/v1/credentials/institutions for institution (universities, colleges, etc.). Search is billable on live; countries/institutions/status/results/history are not billed.

Test data

Sandbox test data

Use these values against the sandbox host. Click a value to copy it.

Sandbox Complete (final catalog hit)

Sandbox Processing (interim catalog)

Sandbox Processing (unknown student)

Sandbox Pending Consent

List countries

Returns countries available for Digital Credentials searches. Use name as country on the search request. Auth required; this call is not billed.

GET/api/v1/credentials/countries

{{baseUrl}}/api/v1/credentials/countries

200 OKSample dataExample response

{
  "success": true,
  "response_code": 200,
  "message": "Countries retrieved successfully",
  "data": {
    "countries": [
      { "name": "Kenya" },
      { "name": "Rwanda" },
      { "name": "Tanzania" },
      { "name": "Uganda" }
    ]
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Field	Type	Description
data.countries	array	Countries that have credential issuers, sorted by name
data.countries[].name	string	Value to send as country when searching

List institutions

Returns institutions (universities, colleges, etc.) available for Digital Credentials searches, each with a name and country. Use name as institution on the search request below. Auth required; this call is not billed.

GET/api/v1/credentials/institutions

{{baseUrl}}/api/v1/credentials/institutions

200 OKSample dataExample response

{
  "success": true,
  "response_code": 200,
  "message": "Institutions retrieved successfully",
  "data": {
    "institutions": [
      { "name": "Kenyatta University", "country": "Kenya" },
      { "name": "University of Nairobi", "country": "Kenya" }
    ]
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Field	Type	Description
data.institutions	array	Institutions sorted by name ascending
data.institutions[].name	string	Value to send as institution when searching
data.institutions[].country	string	Country name of the institution

Search credentials

POST/api/v1/credentials/search

{{baseUrl}}/api/v1/credentials/search

Header

Header	Type	Description
Authorization	string	`Bearer YOUR_ACCESS_TOKEN` from the OAuth client-credentials flow
Content-Type	string	application/json

Body Parameters

Parameter	Type	Description	Required
full_name	string	Student full name (at least first and last name)	required
country	string	Country name from GET /api/v1/credentials/countries (e.g. Kenya)	required
type	string	Transcript \| Certificate \| Both	required
document	file	Credential document to verify (PDF, JPG, or PNG, max 10MB). Required.	required
consent_document	file	Signed consent document (PDF, JPG, or PNG, max 10MB). Always required.	required
certificate	file	Required when type is Both — second document (certificate). PDF, JPG, or PNG, max 10MB.	conditional
student_email	string	Required unless consent is true — used for consent outreach	conditional
institution	string	Institution name from GET /api/v1/credentials/institutions (university, college, etc.)	optional
course	string	Course / programme name	optional
graduation_year	integer	Graduation year (1900–current year)	optional
customer_number	string	Optional reference for your own tracking (max 255 characters)	optional
consent	boolean	true if student consent was already collected; false/omitted triggers Pending Consent + student email outreach	optional
student_pays_consent	boolean	Live only — bill student via consent payment link instead of tenant wallet	optional

Multipart request (document required)

Sample request body for Multipart request (document required):

Sample dataSample request body

curl -X POST "{{baseUrl}}/api/v1/credentials/search" \
  -H "Authorization: Bearer {{token}}" \
  -H "Accept: application/json" \
  -F 'full_name=James Otieno Kamau' \
  -F 'country=Kenya' \
  -F 'type=Transcript' \
  -F 'institution=University of Nairobi' \
  -F 'course=Bachelor of Commerce' \
  -F 'consent=true' \
  -F 'document=@/path/to/transcript.pdf;type=application/pdf' \
  -F 'consent_document=@/path/to/signed-consent.pdf;type=application/pdf'

Sample response for Multipart request (document required):

200 OKSample dataSample response

{
  "success": true,
  "response_code": 200,
  "message": "Credentials search accepted",
  "data": {
    "search_id": 125,
    "status": "Complete"
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Processing (awaiting verification)

Sample request body for Processing (awaiting verification):

Sample dataSample request body

curl -X POST "{{baseUrl}}/api/v1/credentials/search" \
  -H "Authorization: Bearer {{token}}" \
  -H "Accept: application/json" \
  -F 'full_name=Jane Wanjiku Njeri' \
  -F 'country=Kenya' \
  -F 'type=Transcript' \
  -F 'institution=Kenyatta University' \
  -F 'consent=true' \
  -F 'document=@/path/to/transcript.pdf;type=application/pdf' \
  -F 'consent_document=@/path/to/signed-consent.pdf;type=application/pdf'

Sample response for Processing (awaiting verification):

200 OKSample dataSample response

{
  "success": true,
  "response_code": 200,
  "message": "Credentials search accepted",
  "data": {
    "search_id": 126,
    "status": "Processing",
    "message": "The report will be ready within 5 days."
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Response Fields

Field	Type	Description
data.search_id	integer	Use with status and results poll endpoints
data.status	string	Complete = final catalog hit ready now; Processing = awaiting verification; Pending Consent = awaiting student consent
data.message	string	Present when status is Processing — The report will be ready within 5 days.

Set {{baseUrl}} to https://api.peleza.com (production) or https://sandbox.peleza.com (sandbox). Authenticated calls need a Bearer token from POST /api/v1/oauth/token.