How to get started with Physical Identity Proofing

Learn how to get started with integrating your backend to Mobai’s PIP service. Use our REST API to order PIP sessions, track status, and retrieve results securely. This guide covers everything you need to connect your system to Mobai’s ID-kontroll workflow — including handling applicant input data, webhooks, and final report delivery.

Prerequisites:

• Test OAuth 2.0/API key credentials (Please contact Mobai to get credentials)

Resources:

• API docs (Swagger)
• API docs (OpenAPI)

Test environment

1. Create a PIP request with “POST /v1/requestor/pip” with applicant name and phone number in the body. (Remember to use the test base URL). Take note of the pipId and the attendanceCode in the response.

POST /v1/requestor/pip

// Request body
{
  "applicantName": "Bodil Johansen",
  "applicantPhoneNumber": "91010203"
}

2. Finish a PIP with fake identity data with “POST /v1/requestor/pip/{pipId}/finishPipWithFakeData”.

POST /v1/requestor/pip/{pipId}/finishPipWithFakeData

// Request body
{
  "documentHolder": "Bodil Johansen",
  "nationalIdNumber": "01020312345",
  "mrzCode": "P<NOR<<<<<01306623045<<12345<<<5604230M2504115NOR<<<<<<<<<<<SOESTENBYEN<<AASAMUND<SPECIMEN<",
  "docNumber": "45612378",
  "approved": true
}

3. Get PIP request details with “GET /v1/requestor/pip/{pipId}” and check that the status is AWAITING_DOWNLOAD or RESULT_SENT (see below for details).

GET /v1/requestor/pip/{pipId}

// Response
{
  "pipId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "AWAITING_DOWNLOAD",
  "lastUpdated": "2023-06-01T14:30:00Z",
  "attendanceCode": "345265"
}

4. Fetch the customer result with either REST API or Digipost - according to you configuration.

• REST API: Retrieve the result of a completed PIP request in JSON format using "GET /v1/requestor/pip/{pipId}/result". The response includes URLs for the PDF report, XML data, and chip image. Optionally, you can also download a complete ZIP file containing all result files.

• Digipost: You can see the result from a completed PIP request by going to https://www.test.digipost.no/ select “Logg inn med ID-Porten", “Test ID”, put the user ID provided by us in the “Personidentifikator” field and “Autentiser”.

5. (Optional) Set up webhooks.

Explanation of each status field:

CREATED – Before the Applicant have started the PIP process.

PROCESSING – Internal processing at Mobai’s server.

RESULT_SENT – A verification that the case has been sent through to Digipost (if Digipost is used).

AWAITING_DOWNLOAD – If the requestor does not use the Digipost option, this will be the status after a valid identity proofing has been done, and Mobai have not received a request from the customer to the Fetch PIP Report endpoint.

RESULT_DOWNLOADED - If the requestor does not use the Digipost option, this will be status after we have replied with a 200 HTTP status code on a request of a process ID. Mobai do not guarantee that the user of the endpoint has completed its task, and the user of this endpoint should not use this status as confirmation that things have been successful on their side.

EXPIRED – The status shown if the process is not completed within 30 days.

ERROR – Shown if there for some reason has been a technical error during the process. In cases like this, both parties know this has happened. Normally Mobai will fix a bug in cases like this.

AWAITING_APPROVAL - If the PIP is waiting for operator approval. This happens when a new operator has conducted the PIP.

Go live

Use your production OAuth 2.0 credentials (contact Mobai if you haven’t received them). Remember to update the base URL and configure webhooks if applicable.

Additional resources:

Overview of the result in PDF, JSON and XML:

Click to expand

Field name PDF	JSON name	XML name	Format	Source	Note
ID-kontroll bestillingsnummer	pipCode	kollinr	PIP+10-siffer	Backend	<PIP><Applicantcode><MMYY> example: PIP1234560125
Dato og klokkeslett	dateOfProofing	dato	Digits	Backend
Utleveringssted (enhetsnummer og -navn)	locationOfProofing	utleveringssted	Text	Backend	API from Posten
Kundebehandler	registrationOfficer	kundebehandler	Text	App
Dokumentinnehaver	applicantName	navndokinnehaver	Text	App
Bestiller navn	applicantPipRequestName	navnfraedi	Text	Backend
Fødselsdato / fødselsnummer	nationalIdNumber	fnr	Max 11 digits	App
Fødselsnummer / D-nummer	dNumber	dnr	Max 11 digits	App
Type ID-document	idType	idtype	Text	App
Dokumentnummer	nfcData.DocNumber	doknr	Digits	App
Utstedt i (land)	nfcData.Issuer	utstedt	Text	App
Gyldig til	nfcData.ValidUntil	gyldigtil	Digits	App
Tilleggsdokumentasjon		tilleggsdok	Picture	App
MRZ-kode	mrzCode	MRZ-kode	Characters	App	For xml: Max 5 character Get the first character (indicates the ID doc type) and the characters that indicates the issued country example: P-NOR
ID-kontroll	approved	Godkjent	True/False	Backend
	NA	signaturassistent			Always empty
Automatiske kontroller Manuelle kontroller	NA	kontrollstatus	Automatic/Manual (xml)	Backend	Er automatisk/manuelle kontroll gjennomført
RFID-chip lest	automatic.rfidRead	RFIDlest	True/False	App
MRZ Valid	MrzValid	MRZValid	True/False	App	Sjekk på at formatet er riktig. Kan sjekke på om det samsvarer med MRZ som ligger i chip.
	NA	UVValid	True/False		Always empty
	NA	IRValid	True/False		Always empty
Ugyldig operatør / Time out	TerminationCause	Avbrudsgrunn	Text	Backend
Ansiktssammenligning	automatic.biometricComparisonApproval	AnsiktssammenligningA	True/False	Backend
Score sammenligning	automatic.biometricComparisonScore	ScoreAnsiktssammenligning	Text	Backend
Ansiktssammenligning	manual.biometricComparsionApproval	AnsiktssammenligningM	True/False	App
Meldt tapt / stjålet (norske pass)	StatusToveRegister	StatusFraTOVE	Text	Backend	Match / No Match / Unknown Document
RFID-brikke data (PA)	automatic.rfidPassiveAuthentication	RfidPassivAutentisitet	True/False	App	Not signed / Signed / Signed and verified
RFID-brikke data (AA)	automatic.rfidActiveAuthentication	RfidActiveAutentisitet	True/False	App
	pdfUrl		Text	Backend	Used by JSON API to enable downloading of additional information
	imageUrls		Text	Backend

Frequently asked questions:

What are pipId and attendanceCode used for, and what’s the difference between them?

pipId is the unique identifier for the PIP request. Not to be exposed to end customer. attendenceCode is to be sent to end customer for identifying the session when attending the physical identity proofing.

What is the OAuth 2.0 token expiry time?

The token has 60 minutes expiration time for production environment, can vary in test/QA.

Why do approved have true, false and null?

true means that the PIP request have been successfully completed.

false means that the PIP request have been rejected — see the detailed report for specifics.

null means the process was either incomplete or failed. This typically occurs when the Registration Officer/Operator rejects the applicant. The reason for rejection can be found in the field terminationCause.

nationalIdentitynumber is that the Norwegian ID number, number on ID doc or d-number?

This is the Norwegian identity number (fødselsnummer) or Norwegian D-number.

Will the PIP result still be approved if the applicant’s name differs slightly from the name on the ID document?

Yes - slight name variations is approved upon the Applicant Officer/Operator’s judgement and according to their training.

Will we get the signature from the ID document in the result?

Yes, even if the signature is on the “back” side of the ID document the operator is asked to take another picture of the signature page. (Note: Some foreign ID documents does not have a signature).

Can we use both Digipost and the API for downloading customer reports?

Yes, you can use both. Inform Mobai about this so we can set it up correctly for you.

Can we use polling instead of webhooks?

Yes, you can. Please be considerate of the polling interval.

What is the expected request and response for persons under 18 years old? Which name and phone number should be used?

When placing an order for an individual under 18, the name provided must match the name on the ID document of the holder (the childs name).

If a customer is under 18, a parent or guardian may enter either their own phone number or the child's when placing the order. During ID verification, this number must be provided.

For individuals under the age of 18, no photograph will be taken. The PIP report will not contain the face image and any automated face verification checks, only picture collected from the ID document and manual ID check result.

Available resources for download:

• Check list for the main tasks that needs to be in place (in Norwegian): Download check list
• Template for customer communication used with your customer (in Norwegian): Download customer communication template