Organization

The Organization module manages client-level configuration for an authenticated Sipajak account. It exposes the client's profile, usage and history of past API calls, and the ability to register additional NPWPs against an existing credential pair. New NPWPs must be registered through this module before they can appear in the npwp header of any other endpoint.

All endpoints in this module are scoped to the authenticated client. The npwp header still must be present on every request (it identifies which registered NPWP the call acts on behalf of), but the underlying data — profile, history rows, registered organisations — belongs to the client account as a whole, not to an individual NPWP.

4.1 Endpoint summary

4.2 Profile

The profile holds metadata about the authenticated client: contact information, certificate configuration for signing, signatory defaults, webhook configuration, and status flags. It is exposed through a single resource available via GET and POST on the same path.

4.2.1 Get profile

GET /v1/profile

Returns the authenticated client's profile.

Request headers

Query parameters

Example request

GET /v1/profile HTTP/1.1
Host: gateway-integration.sipajak.com
Authorization: Basic <base64-encoded credentials>
npwp: 1234567890123000

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
  "status_code": 200,
  "message": "OK",
  "data": {
    "npwp": "1234567890123000",
    "name": "PT Contoh Sejahtera",
    "email": "contact@example.com",
    "phone_number": "628120000000",
    "address": "Jalan Contoh No. 1, Jakarta 12345",
    "signatory_type": "INDIVIDUAL",
    "signatory_name": "Budi Santoso",
    "signatory_position": "Direktur",
    "signatory_city": "Jakarta",
    "status_efaktur": "ACTIVE",
    "status_efaktur_message": null,
    "webhook_url": null,
    "webhook_key": null
  }
}

Response fields

4.2.2 Update profile

POST /v1/profile

Updates one or more profile fields.

Partial-update semantics. Despite using HTTP POST, this endpoint performs a partial (PATCH-like) update. Only fields included in the request body are persisted; omitted fields are left unchanged. This is a Sipajak convention and may surprise REST-oriented clients expecting POST to mean full replacement.

When updating the signing certificate, the request must be sent as multipart/form-data with the certificate file under the field certificate_file. All other fields may then be sent as form fields. For non-certificate updates, plain application/json is accepted.

Request body — fields

Example request

POST /v1/profile HTTP/1.1
Host: gateway-integration.sipajak.com
Authorization: Basic <base64-encoded credentials>
npwp: 1234567890123000
Content-Type: application/json
{
  "phone_number": "628120000000",
  "signatory_position": "Direktur Utama"
}

The response is the same shape as GET /v1/profile, reflecting the updated state.

4.3 Usage

GET /v1/usage

Returns API usage and quota consumption for the authenticated client. Usage is calculated from a per-call billing journal: each chargeable API call contributes to the total according to a per-endpoint price. There is no static "quota limit" field — caps are enforced by Sipajak commercially and surfaced via this endpoint as cumulative consumption against the billing window.

Query parameters

Example request

GET /v1/usage?start_date=2026-04-01&end_date=2026-04-30 HTTP/1.1
Host: gateway-integration.sipajak.com
Authorization: Basic <base64-encoded credentials>
npwp: 1234567890123000

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
  "status_code": 200,
  "message": "OK",
  "data": {
    "start_date": "2026-04-01",
    "end_date": "2026-04-30",
    "total_calls": 12450,
    "total_charged": 9876,
    "total_price": 4938000,
    "by_module": [
      { "module": "vswp",    "calls": 8200, "charged": 6500, "price": 1300000 },
      { "module": "efaktur", "calls": 3100, "charged": 2800, "price": 2800000 },
      { "module": "ebupot",  "calls": 1150, "charged":  576, "price":  838000 }
    ]
  }
}

Note. The exact response shape is subject to confirmation against staging. The example above reflects the documented contract of the underlying summary query. Fields total_calls, total_charged, and total_price represent the count of API calls made, the subset that incurred a charge (some lookups are cached or otherwise free), and the cumulative price in IDR rupiah respectively.

4.4 Histories

GET /v1/histories

Returns a paginated history of past API calls made by the authenticated client. Each row represents a single billable / DJP-bound request — Sipajak meta endpoints such as profile and usage are not currently captured in this history.

The most common use is to look up a specific past call by its correlation UUID — for debugging an integration issue or for retrieving the original request/response payload of a Faktur or Bupot submission days or weeks after the fact.

Query parameters

Example — lookup by correlation UUID

GET /v1/histories?code=da862a83-c667-4e64-a20d-72b2ed70833c HTTP/1.1
Host: gateway-integration.sipajak.com
Authorization: Basic <base64-encoded credentials>
npwp: 1234567890123000

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
  "status_code": 200,
  "message": "OK",
  "data": {
    "items": [
      {
        "code": "da862a83-c667-4e64-a20d-72b2ed70833c",
        "npwp": "1234567890123000",
        "route": "/v2/vswp",
        "module_id": "vswp",
        "endpoint_id": "vswp.validate",
        "status": "SUCCESS",
        "is_charge": true,
        "price": 200,
        "history_date": "2026-05-08",
        "created_time": "2026-05-08T10:23:45.123Z",
        "request":  "{\"npwp\":\"3201234567890000\",\"tujuan\":\"Validasi NPWP\"}",
        "response": "{\"status\":\"1\",\"statusMessage\":\"Success\",\"result\":{...}}"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 10
  }
}

Row fields

Scope of capture. The histories endpoint captures DJP-bound and billable calls. Meta endpoints (/v1/profile, /v1/usage, /v1/histories itself, /v1/organization) are not stored here. To look up the full set of past calls including meta endpoints, contact the Sipajak API team — server-side audit logs can be consulted on request.

4.5 Register additional NPWP

POST /v1/organization

Registers an additional NPWP against the authenticated credential pair. After registration the new NPWP can be used in the npwp header on subsequent requests.

HTTP 201 on success. Unlike most Sipajak endpoints, a successful response from this endpoint returns HTTP 201 (Created), not 200. The envelope's status_code field reflects the same value.

Request body

Example request

POST /v1/organization HTTP/1.1
Host: gateway-integration.sipajak.com
Authorization: Basic <base64-encoded credentials>
npwp: 1234567890123000
Content-Type: application/json
{
  "npwp": "2345678901234000",
  "npwp16": "3201234567890000",
  "name": "PT Contoh Sejahtera",
  "email": "contact@example.com",
  "phone_number": "628120000000",
  "address": "Jalan Contoh No. 1, Jakarta 12345",
  "logo": "https://cdn.example.com/logo.png",
  "type": "COMPANY",
  "is_active": true,
  "is_government": false,
  "apj_name": "Budi Santoso",
  "apj_position": "Direktur",
  "apj_phone_number": "628120000001"
}

Example response — success

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
{
  "status_code": 201,
  "message": "Created",
  "data": {
    "organization_id": "0192a3b4-c5d6-7890-abcd-ef1234567890",
    "npwp": "2345678901234000",
    "npwp16": "3201234567890000",
    "name": "PT Contoh Sejahtera",
    "type": "COMPANY",
    "is_active": true,
    "is_government": false,
    "created_time": "2026-05-12T03:45:12.000Z"
  }
}

Example response — duplicate NPWP

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
{
  "status_code": 400,
  "message": "Bad Request Exception",
  "error": "NPWP sudah terdaftar."
}

Header NPWP on this endpoint. The npwp header on POST /v1/organization names an NPWP already registered to the credential — typically the client's primary organisation. The NPWP being newly registered is the value of body.npwp, not the header.

4.6 Error handling