Skip to main content

Physical Identity Proofing API

Resources​

Sequence diagram​

Authentication​

The API is secured with OAuth2.0. All requests to protected endpoints must include a valid access token obtained from the OAuth 2.0 authorization server.

Obtaining an access token​

Request access token

curl -X POST https://api.example.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Using the access token​

All requests to protected endpoints must include the access token in the Authorization header.

Authorization: Bearer <access_token>

Services​

POST /v1/requestor/pip​

Create a new Physical Identity Proofing (PIP) request.

Request example:

{
  "applicantName": "John Doe",
  "applicantPhoneNumber": "99995555"
}

Response example:

{
  "pipId": "B1A5346C-32BD-43A8-BE32-B47D5A107108",
  "status": "CREATED",
  "lastUpdated": "2025-10-01T14:20:00Z",
  "attendanceCode": "123456"
}

POST /v1/requestor/pip/{pipId}/cancel​

Cancel a PIP request. Only possible if status is CREATED.

Response example:

{
  "attendanceCode": "123456",
  "pipId": "B1A5346C-32BD-43A8-BE32-B47D5A107108",
  "status": "CANCELLED",
  "lastUpdated": "2025-10-07T12:20:24.075439Z"
}

GET /v2/requestor/pip/{id}/result​

Get the current status and result of a PIP request, if the physical identity control has been completed.

Response example when completed and approved:

{
  "pipId": "B1A5346C-32BD-43A8-BE32-B47D5A107108",
  "applicantName": "John Doe",
  "pipStatus": "AWAITING_DOWNLOAD",
  "approved": true,
  "completed": true,
  "terminationCause": null,
  "proofingSessionDetails": {
    "locationOfProofing": "Lagunen Post i Butikk, OBS Lagunen",
    "dateOfProofing": "2025-10-03T13:24:25.019522Z",
    "registrationOfficer": "Ole Olsen"
  },
  "proofingData": {
    "toveStatus": "NO_MATCH",
    "automaticRfidRead": true,
    "automaticBiometricComparisonApproval": true,
    "automaticBiometricComparisonScore": 0.84046376,
    "automaticRfidPassiveAuthentication": "AUTHENTICATED",
    "automaticRfidActiveAuthentication": "AUTHENTICATED",
    "manualBiometricComparisonApproval": true,
    "idNumberManuallyEntered": false,
    "nfcData": {
      "idType": "PASSPORT",
      "nationalIdNumber": "01019912345",
      "documentHolder": "Aasmund Specimen",
      "documentHolderSurname": "Specimen",
      "documentHolderGivenNames": "Aasmund",
      "gender": "MALE",
      "nationality": "NOR",
      "birthdate": "1999-01-01",
      "mrzCode": "XANORJGD0004758230456<12345<<<, 5604230M2606118XXX<<<<<<<<<<<9, OESTENBYEN<<AASAMUND<SPECIMEN<",
      "mrzValid": true,
      "nfcDataIssuer": "NOR",
      "nfcDataDocNumber": "CCC002251",
      "nfcDataValidUntil": "2030-01-01"
    },
    "files": {
      "chipImage": "https://test.idkontroll.mobai.no/v1/requestor/pip/B1A5346C-32BD-43A8-BE32-B47D5A107108/result/chipImage",
      "identityCardImage": "https://test.idkontroll.mobai.no/v1/requestor/pip/B1A5346C-32BD-43A8-BE32-B47D5A107108/result/identityCardImage",
      "identityCardImage2": "https://test.idkontroll.mobai.no/v1/requestor/pip/B1A5346C-32BD-43A8-BE32-B47D5A107108/result/identityCardImage2",
      "personImage": "https://test.idkontroll.mobai.no/v1/requestor/pip/B1A5346C-32BD-43A8-BE32-B47D5A107108/result/personImage",
      "pdf": "https://test.idkontroll.mobai.no/v1/requestor/pip/B1A5346C-32BD-43A8-BE32-B47D5A107108/result/pdf"
    }
  }
}

Response example when terminated because of mismatch phone number:

{
  "pipId": "B1A5346C-32BD-43A8-BE32-B47D5A107108",
  "applicantName": "John Doe",
  "pipStatus": "AWAITING_DOWNLOAD",
  "approved": null,
  "completed": false,
  "terminationCause": "MISMATCH_PHONE",
  "proofingSessionDetails": null,
  "proofingData": null
}
  • When pip request is created by requestor:
    • status is CREATED
    • approved is null
    • completed is false.
    • proofingSessionDetails and proofingData is null
  • When physical identity proofing is completed:
    • status is RESULT_SENT, AWAITING_DOWNLOAD or RESULT_DOWNLOADED
    • approved is true or false
    • completed is true
    • proofingSessionDetails and proofingData is present
  • When pip request has been cancelled by requestor:
    • status is CANCELLED
    • approved is null
    • completed is false
    • proofingSessionDetails and proofingData is null
  • When terminated:
    • status is RESULT_SENT, AWAITING_DOWNLOAD or RESULT_DOWNLOADED
    • approved is null
    • completed is false
    • terminationCause is present

Fields​

Explanation of status​

  • 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 of the PIP after 30 days. Collected customer data can not be retrieved after this deadline. 
  • 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 - This happens when the PIP is waiting for administrator approval due to use of forgotten PIN-function during a PIP session with a customer.
  • CANCELLED - This happens when the PIP is cancelled by the requestor. (Only possible if status is CREATED)

Explanation of terminationCause​

  • ID_CODE_EXPIRED - The code provided to the user has expired
  • MISMATCH_PHONE - The phone number provided by the user does not match the one used for verification
  • MISMATCH_ID_DOC - The ID document presented does not match the expected type or format
  • MISMATCH_NAME - The name on the ID document does not match the name provided by the user
  • MISMATCH_FACE - The face comparison did not match
  • ID_DOC_EXPIRED - The ID document presented has expired
  • ID_CARD_FOREIGN - The ID card presented is foreign and cannot be accepted
  • ID_DOC_NOT_VALID - The ID document presented is not valid or recognized
  • TERMINATED - Other reason for termination at registration office
  • UNKNOWN - Unknown reason

Explanation of toveStatus​

  • NO_MATCH - The ID document has not been reported as lost or stolen
  • MATCH - The ID document has been reported as lost or stolen