---
updatedAt: 2025-09-17T09:15:14.000Z
agentTools:
  projectIndex: https://docs.verihubs.com/llms.txt
---

# API Request & Response

# 🎈Headers

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th style={{ textAlign: "left" }}>
        Key
      </th>

      <th style={{ textAlign: "left" }}>
        Type
      </th>

      <th style={{ textAlign: "left" }}>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td style={{ textAlign: "left" }}>
        App-ID
      </td>

      <td style={{ textAlign: "left" }}>
        String
      </td>

      <td style={{ textAlign: "left" }}>
        Application ID that generated from Application Menu in Verihubs Client Dashboard.
        To hit in Testing and Live mode you need a Production Application ID.
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>
        API-Key
      </td>

      <td style={{ textAlign: "left" }}>
        String
      </td>

      <td style={{ textAlign: "left" }}>
        API-Key that generated from Application Menu in Verihubs Client Dashboard that related to specific Application ID.
      </td>
    </tr>
  </tbody>
</Table>

You can generate your Application ID and API-Key in the [Application page in Verihubs Client Dashboard.](https://app.verihubs.com/cloud/application).

# 🎈Request Details

## Request Parameter for NIK Endpoint

<Table align={["left","left","left","left"]}>
  <thead>
    <tr>
      <th>
        Payloads
      </th>

      <th>
        Type
      </th>

      <th>
        Description
      </th>

      <th>
        Example
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        nik
      </td>

      <td>
        string
      </td>

      <td>
        16-digit of Wajib Pajak's NIK as stated on KTP.
      </td>

      <td>
        1234567891234567
      </td>
    </tr>

    <tr>
      <td>
        purpose
      </td>

      <td>
        string
      </td>

      <td>
        The main purpose of validation. Currently there is no number of character limitation in this payload.
      </td>

      <td>
        Pengecekan status WP
      </td>
    </tr>

    <tr>
      <td>
        user_consent
      </td>

      <td>
        boolean
      </td>

      <td>
        When user_consent is true, the response will show the user's NPWP along with the validation status.

        When user_consent is false, the response will only show the validation status without showing user's NPWP.
      </td>

      <td>
        true
      </td>
    </tr>

    <tr>
      <td>
        reference_id
      </td>

      <td>
        string
      </td>

      <td>
        ID that can be generated from your side to indicate your company's transaction. Must be unique per transaction. Verihubs will also auto-generate this ID if it left empty/non-exist in the payload.
      </td>

      <td>
        npwp#123456
      </td>
    </tr>
  </tbody>
</Table>

## Request Parameter for NPWP Endpoint

<Table align={["left","left","left","left"]}>
  <thead>
    <tr>
      <th>
        Payloads
      </th>

      <th>
        Type
      </th>

      <th>
        Description
      </th>

      <th>
        Example
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        npwp
      </td>

      <td>
        string
      </td>

      <td>
        Wajib Pajak's NPWP as stated on NPWP card and has to be inputted without the point (.) and strip (-) symbols that are shown in the Kartu NPWP. Verihubs accepts these formats of NPWP:

        * 15 digit NPWP.
        * 16 digit NPWP.
        * 22 digit NITKU.
      </td>

      <td>
        If the NPWP written on NPWP card is 01.002.003.4-056.000, then input it as is 010020034056000
      </td>
    </tr>

    <tr>
      <td>
        purpose
      </td>

      <td>
        string
      </td>

      <td>
        The main purpose of validation. Currently there is no number of character limitation in this payload.
      </td>

      <td>
        Pengecekan status WP
      </td>
    </tr>

    <tr>
      <td>
        user_consent
      </td>

      <td>
        boolean
      </td>

      <td>
        When user_consent is true, the response will show the user's NPWP along with the validation status.

        When user_consent is false, the response will only show the validation status without showing user's NPWP.
      </td>

      <td>
        true
      </td>
    </tr>

    <tr>
      <td>
        reference_id
      </td>

      <td>
        string
      </td>

      <td>
        ID that can be generated from your side to indicate your company's transaction. Must be unique per transaction. Verihubs will also auto-generate this ID if it left empty/non-exist in the payload.
      </td>

      <td>
        npwp#123456
      </td>
    </tr>
  </tbody>
</Table>

> 🚧 Hitting the Verihubs Tax Number Verification endpoint(s) with both the NPWP and NIK in the same endpoint will result in an INVALID\_PAYLOAD response.

# 🎈Response Details

## Response Parameter for NIK and NPWP Endpoint

| Response      | Type   | Description                                                                                                                              | Examples                                           |
| :------------ | :----- | :--------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------- |
| message       | String | Status of the transaction                                                                                                                | Successfully check NPWP                            |
| id            | String | 32-digit auto-generated Verihubs transaction ID                                                                                          | 123a4a56-7b8c-91a2-34b5-67a8e9a1234a               |
| reference\_id | String | ID that can be generated from your side to indicate your company's transaction. Must be unique.                                          | npwp#123456                                        |
| npwp          | String | NPWP from the inputted NIK if user\_consent is set TRUE                                                                                  | 010020034056000                                    |
| nama          | String | Masked registered name of the NPWP owner.                                                                                                | J\*HN D\*\*                                        |
| alamat        | String | Masked registered address of the NPWP owner.                                                                                             | W\_K TW\_R 1, JL D.. P\_NJ\*\_T\_N K\_V. 9 001 011 |
| status\_wp    | String | The Wajib Pajak (WP) status of the associated NPWP that will be shown as **AKTIF** or **NE** (re: Non Efektif).                          | AKTIF                                              |
| status\_spt   | String | The Surat Pemberitahuan (SPT) Tahunan status of the associated NPWP for the last 2 years that will be shown as **VALID** or **INVALID**. | VALID                                              |

## Detailed Response

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Code
      </th>

      <th>
        Description
      </th>

      <th>
        Response
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        200
      </td>

      <td>
        _Successful Request_*; This is a transaction that is considered successful and has been successfully verified by the data source)
      </td>

      <td>
        ```json
        { 
          "message": "Successfully check NPWP", 
          "data": { 
            "id": "Transaction ID", 
            "referenceid": "Reference ID from Client", 
            "npwp": "NPWP Number", 
            "nama": "Masked Name", 
            "alamat": "Masked Address", 
            "status_wp": "AKTIF/NE", 
            "status_spt": "VALID/INVALID" 
          } 
        }

        ```
      </td>
    </tr>

    <tr>
      <td>
        200
      </td>

      <td>
        Successfull Request but NPWP Not Found. This indicates that the searched NPWP by NIK is not registered in the datasource.
      </td>

      <td>
        ```json
        {
        "message": "NPWP not found",
        "data": \{
        "id": "4182b248-f323-4c57-a770-15b4ea4c4968",
        "reference_id": "Reference ID from client",
        "npwp": null,
        "nama": null,
        "alamat": null,
        "status_wp": null,
        "status_spt": null
        }
        }
        ```
      </td>
    </tr>

    <tr>
      <td>
        400
      </td>

      <td>
        _Bad Request_*; This is a transaction that is considered failed due to validation errors, an error_field will appear explaining the error.
      </td>

      <td>
        ```json
        {
        "message": "Authorization Failed",
        "error_code":    "BAD REQUEST",
        "error_fields": []
        }
        ```
      </td>
    </tr>

    <tr>
      <td>
        401
      </td>

      <td>
        _Authorization Failed_*; The transaction cannot proceed because it is unauthorized.
      </td>

      <td>
        ```json
        {
        "message": "Authorization Failed",
        "error_code":    "UNAUTHORIZED",
        "error_fields": []
        }
        ```
      </td>
    </tr>

    <tr>
      <td>
        403
      </td>

      <td>
        _Insufficient Quota_*; The transaction failed due to insufficient quota, please contact Verihubs Customer Success (CS) Team.
      </td>

      <td>
        ```json
        {
        "message": "Insufficient testing quota",
        "error_code": "FORBIDDEN",
        "error_fields": []
        }
        ```
      </td>
    </tr>

    <tr>
      <td>
        429
      </td>

      <td>
        _Spam Error_*; The transaction is read as spam, please wait a few seconds before re-performing the hit process.
      </td>

      <td>
        ```json
        {
        "message": "Too many request in the allowed time frame",
        "error_code":       "TOO_MANY_REQUEST",
        "error_fields": []
        }
        ```
      </td>
    </tr>

    <tr>
      <td>
        500
      </td>

      <td>
        _Internal Server Error_*; The transaction failed due to a server error that could be caused by data source constraints, timeout, internal error.
      </td>

      <td>
        ```json
        {
        "message": "Internal Server Error",
        "error_code":    "INTERNAL_SERVER_ERROR",
        "error_fields": []
        }
        ```
      </td>
    </tr>
  </tbody>
</Table>

### NIK, NPWP and User Consent Variations

<Table align={["left","left","left","left","left"]}>
  <thead>
    <tr>
      <th>
        Payload Used
      </th>

      <th>
        User Consent
      </th>

      <th>
        Request
      </th>

      <th>
        Response
      </th>

      <th>
        Remarks
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        NIK
      </td>

      <td>
        True
      </td>

      <td>
        ```json
        {
        **"nik": "true NIK",**
        "purpose": "real purpose",
        **"user_consent": true,**
        “reference_id”: “Client Generated Reference ID”
        }
        ```
      </td>

      <td>
        ```json
        {
        "message": "Successfully check NPWP",
        "data": {
        "id": "Transaction ID",
        "referenceid": "Reference ID from Client",
        **"npwp": "NPWP Number",**
        "nama": "Masked Name",
        "alamat": "Masked Address",
        "status_wp": "AKTIF/NE",
        "status_spt": "VALID/INVALID"
        }
        }
        ```
      </td>

      <td>
        The NPWP number will be shown if the NIK payload is being used and user_consent is true.
      </td>
    </tr>

    <tr>
      <td>
        NIK
      </td>

      <td>
        False/Empty/Not Exist
      </td>

      <td>
        ```json
        {
        **"nik": "true NIK",**
        "purpose": "real purpose",
        **"user_consent": false,**
        “reference_id”: “Client Generated Reference ID”
        }
        ```
      </td>

      <td>
        ```json
        {
        "message": "Successfully check NPWP",
        "data": {
        "id": "Transaction ID",
        "referenceid": "Reference ID from Client",
        "nama": "Masked Name",
        "alamat": "Masked Address",
        "status_wp": "AKTIF/NE",
        "status_spt": "VALID/INVALID"
        }
        }
        ```
      </td>

      <td>
        The NPWP number will not be shown if the NIK payload is being used and user_consent is false.
      </td>
    </tr>

    <tr>
      <td>
        NPWP
      </td>

      <td>
        True/False/Empty/Not Exist
      </td>

      <td>
        ```json
        {
        **"npwp": "true NPWP",**
        "purpose": "real purpose",
        **"user_consent": true,**
        “reference_id”: “Client Generated Reference ID”
        }
        ```
      </td>

      <td>
        ```json
        {
        "message": "Successfully check NPWP",
        "data": {
        "id": "Transaction ID",
        "referenceid": "Reference ID from Client",
        "nama": "Masked Name",
        "alamat": "Masked Address",
        "status_wp": "AKTIF/NE",
        "status_spt": "VALID/INVALID"
        }
        }
        ```
      </td>

      <td>
        The user_consent payload will be ignored if the NPWP is being used for the verification.
      </td>
    </tr>

    <tr>
      <td>
        NIK + NPWP
      </td>

      <td>
        True/False/Empty/Not Exist
      </td>

      <td>
        ```json
        {
        **"nik": "true NIK",**
        **“npwp”: “true NPWP”,**
        "purpose": "real purpose",
        **"user_consent": true**
        }
        ```
      </td>

      <td>
        ```json
        {
        "message": "Invalid payload",
        "error_code": "INVALID_PAYLOAD",
        "error_fields": "h-2": "Description",
        "0-0": "App-ID",
        "0-1": "String",
        "0-2": "Application ID that gen
        }
        ```
      </td>

      <td>
        Only a single request payload option between NIK or NPWP is allowed to be used.
      </td>
    </tr>
  </tbody>
</Table>

### Reference ID Variations

<Table align={["left","left","left","left"]}>
  <thead>
    <tr>
      <th>
        Client Reference ID
      </th>

      <th>
        Request
      </th>

      <th>
        Response
      </th>

      <th>
        Remarks
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        Client Generated
      </td>

      <td>
        ```json
        {
        "nik": "true NIK",
        "purpose": "real purpose",
        "user_consent": true,
        “reference_id”: “Client Generated Reference ID”
        }
        ```
      </td>

      <td>
        ```json
        {
        "message": "Successfully check NPWP",
        "data": {
        "id": "Transaction ID",
        "referenceid": "Client Generated Reference ID",
        "npwp": "NPWP Number",
        "nama": "Masked Name",
        "alamat": "Masked Address",
        "status_wp": "AKTIF/NE",
        "status_spt": "VALID/INVALID"
        }
        }
        ```
      </td>

      <td>
        The response will show the exact same Reference ID if the client chooses to generate it by themself.
      </td>
    </tr>

    <tr>
      <td>
        Empty

        _or_

        Not Exist
      </td>

      <td>
        ```json
        {
        "nik": "true NIK",
        "purpose": "real purpose",
        "user_consent": true,
        “reference_id”: “”
        }
        ```
      </td>

      <td>
        ```json
        {
        "message": "Successfully check NPWP",
        "data": {
        "id": "Transaction ID",
        **"referenceid": "Verihubs Generated Reference ID",**
        "npwp": "NPWP Number",
        "nama": "Masked Name",
        "alamat": "Masked Address",
        "status_wp": "AKTIF/NE",
        "status_spt": "VALID/INVALID"
        }
        }
        ```
      </td>

      <td>
        Verihubs will generate a specific Reference ID if within the request payload client doesn’t include ones.
      </td>
    </tr>
  </tbody>
</Table>