VSWP — Validasi Status Wajib Pajak

VSWP (Validasi Status Wajib Pajak) is Sipajak's interface to DJP's Coretax CTAS (Taxpayer Application Services). It answers a single question: is this NPWP or NIK registered with DJP, and what is its profile?

5.1 Endpoint summary

5.2 Single lookup

POST /v2/vswp

Looks up a single NPWP or NIK against DJP Coretax CTAS and returns the taxpayer profile.

Soft-error endpoint. This is a DJP-passthrough endpoint. HTTP 200 is returned even when the taxpayer is not found. Inspect data.status ("1" = success, "0" = business failure).

Results are cached server-side for 90 days keyed on (npwp, tujuan). Repeat lookups within the TTL window return in roughly 10ms without consulting DJP.

No format validation. The endpoint accepts any string in body.data.npwp and forwards it to DJP. Malformed identifiers receive the same "Wajib Pajak tidak ditemukan" response as non-existent ones. Validate format client-side if you need strict checking — 15-digit legacy NPWP, 16-digit harmonised NPWP, or 16-digit NIK.

Request headers

Request body

Example request

POST /v2/vswp HTTP/1.1
Host: gateway-integration.sipajak.com
Authorization: Basic <base64-encoded credentials>
npwp: 1234567890123000
Content-Type: application/json
{
  "npwp": "3201234567890000",
  "tujuan": "Validasi NPWP"
}

Response — success (taxpayer found)

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
  "status_code": 200,
  "message": "OK",
  "data": {
    "status": "1",
    "statusMessage": "Success",
    "result": {
      "npwp": "3201234567890000",
      "nama": "Budi Santoso",
      "alamat": "Jalan Contoh No. 1, Jakarta 12345",
      "statusWp": "VALID",
      "statusSpt": "VALID"
    },
    "uuid": "9fc2be05-9882-42da-8f80-02050aa84393"
  }
}

Response — not found (or malformed input)

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
  "status_code": 200,
  "message": "OK",
  "data": {
    "status": "0",
    "statusMessage": "Wajib Pajak tidak ditemukan",
    "uuid": "b9bebf93-102c-4d7b-a884-80b2c5490e23"
  }
}

Response data fields

5.3 Bulk lookup flow

The bulk flow is a standard submit-poll-download pattern. There are no webhooks; the client polls for completion.

5.3.1 Step 1 — Submit

POST /v1/vswp/bulking

Submits a CSV file of NPWPs/NIKs for asynchronous validation. The response carries a job identifier used for polling and download.

Async-job endpoint. The response envelope contains only job_id — no status, statusMessage, or uuid. See section 3.1.1. Bulk submissions are not idempotent. Submitting the same file twice produces two job_ids and two jobs.

Request

Example CSV content (header row plus 2 data rows):

NPWP,Tujuan
3201234567890000,Validasi NPWP
3301234567890000,Validasi NPWP

Notes on the CSV format:

• Header row is required — first row must contain the column names NPWP and Tujuan (case-sensitive).
• NPWP column — one identifier per row. Accepts 15-digit legacy NPWP, 16-digit harmonised NPWP, or 16-digit NIK. Same format rules as the single-lookup endpoint.
• Tujuan column — business reason for the lookup. Use Validasi NPWP or Konfirmasi NPWP. The value applies per row, so a single file can mix purposes.

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
  "status_code": 200,
  "message": "OK",
  "data": {
    "job_id": "70a6abf1-595f-4b24-ac4f-b368f4ebf671"
  }
}

5.3.2 Step 2 — Poll for status

GET /v1/vswp/{id}

Returns the current state of a bulk job. Poll with a 5- to 10-second interval until data.status equals "COMPLETED". Do not poll more frequently than once per second.

Path parameters

Response — processing

{
  "status_code": 200,
  "message": "OK",
  "data": {
    "job_vswp_id": "70a6abf1-595f-4b24-ac4f-b368f4ebf671",
    "inprogress": 3,
    "total": 10,
    "status": "PROCESSING",
    "created_time": "2026-05-11T16:00:00.000Z",
    "log_vswp": [ /* per-row results, populated incrementally */ ]
  }
}

Response — completed

{
  "status_code": 200,
  "message": "OK",
  "data": {
    "job_vswp_id": "70a6abf1-595f-4b24-ac4f-b368f4ebf671",
    "inprogress": 10,
    "total": 10,
    "status": "COMPLETED",
    "created_time": "2026-05-11T16:00:00.000Z",
    "log_vswp": [
      {
        "request": {
          "data": { "npwp": "3201234567890000", "tujuan": "Validasi NPWP" },
          "params": {}
        },
        "response": {
          "status": "1",
          "statusMessage": "Success",
          "result": {
            "npwp": "3201234567890000",
            "nama": "Budi Santoso",
            "alamat": "Jalan Contoh No. 1, Jakarta 12345",
            "statusWp": "VALID",
            "statusSpt": "VALID"
          }
        },
        "response_time": "0.47"
      }
    ]
  }
}

Response data fields

Known quirks. • The submit response calls the identifier job_id; the status response calls the same value job_vswp_id. They refer to the same UUID. • The inprogress field is misleadingly named — it counts rows already processed, not rows currently being processed. • log_vswp may be populated incrementally during processing; treat it as definitive only when status === "COMPLETED".

5.3.3 Step 3 — Download the result

GET /v1/vswp/{id}/export

Returns the bulk validation result as a CSV file. Only call this when the job's data.status is "COMPLETED".

Response headers

CSV columns (in order)

Example CSV output

"NPWP","Tujuan","Status","Nama","Alamat","Status WP","Status SPT","Response Time(ms)"
"3201234567890000","Validasi NPWP",,"Budi Santoso","Jalan Contoh No. 1, Jakarta
12345","VALID","VALID","0.47"
"3301234567890000","Validasi NPWP",,"Siti Aminah","Jalan Mawar No. 5, Surabaya
60111","VALID","VALID","0.45"

Quirks to handle in client code. • Filename pattern is VSWP-2026 — no .csv extension, and the value reflects the year, not the job_id. Append .csv when persisting the file programmatically. • The Status column (between Tujuan and Nama) is always empty. Treat as reserved. • Column header reads Response Time(ms) but values are seconds (e.g. "0.47" means 470ms).

5.4 Choosing between single and bulk

For loops of single lookups, traffic is dominated by cache hits after the first pass — there is no meaningful speed advantage to switching to bulk for small sets. Bulk is preferred when the input set is large enough that the polling overhead is amortised across many rows, or when the input arrives as a file and CSV upload is the natural shape.

5.5 Error handling reference

The table below maps common situations to the response the client will observe.