# API structure

This page covers how Partner API requests and responses are shaped.

## URL structure

Endpoints follow this pattern:

```
https://{host}/v1/{resource}
```

Endpoint paths align with the NowInfinity platform — what is called Companies in NowInfinity is `/companies` in the API, so if you know the product you can usually guess the path.

**Examples**

```
GET  /v1/accounts
GET  /v1/documents
GET  /v1/documents/{documentId}
GET  /v1/documents/{documentId}/files
GET  /v1/companies/{companyIdOrAcn}
POST /v1/forms/process
```

See [Environments](/products/nowinfinity/resources/environments) for the host to use, and the [API reference](/products/nowinfinity/apis) for the full endpoint list.

## Request headers

| Header | Description |
|  --- | --- |
| `Authorization` | Required. Your access token as a Bearer token: `Authorization: Bearer {access_token}`. |
| `Content-Type` | `application/json` for requests with a body. |
| `X-NI-AccountID` | Optional. Targets a child account. See [Accessing child accounts](/products/nowinfinity/resources/child-accounts). |


## Responses

Successful responses return JSON. A request for a single resource returns that object; a collection endpoint returns an array.

Most resources include a `Links` array alongside their data, pointing at related resources and available actions. See [Following links](/products/nowinfinity/resources/following-links).

## Status codes

| Status | Meaning |
|  --- | --- |
| `200` | The request succeeded. |
| `201` | The resource was created. Creating a form returns the new document's identifier. |
| `202` | Accepted, but not finished. Returned while document files are still being generated — retry later. |
| `204` | No content. Returned when files have not been generated because the document is still in draft. |
| `400` | The request was invalid. The response body identifies which fields failed. |
| `401` | Authentication is missing or invalid. |
| `403` | The token is valid but does not grant access to this resource. |
| `404` | The resource does not exist, or is not visible to the account you are acting as. |


See [Error codes](/products/nowinfinity/resources/error-codes) for response bodies and how to handle each case.

## Asynchronous operations

Some operations do not complete immediately. Generating document files is the main one: creating a form produces a draft with no files, and submitting it for processing starts generation in the background.

That means a `202` is a normal part of the flow rather than an error. Poll the files endpoint until it returns `200`, backing off between attempts rather than retrying tightly.

Processing may also pause for reasons outside the API — where manual handling or payment is required, for example — so treat generation as something that may take a while, not something that always completes in seconds.

## A first request

Once you have a token, the accounts endpoint is the simplest way to confirm everything works:

```bash
curl https://partnerapi.nowinfinity-test.com.au/v1/accounts \
  -H "Authorization: Bearer {access_token}"
```

A `200` with your account in the response means your credentials, scopes and environment are all correct.

## Related

- [Querying with OData](/products/nowinfinity/resources/querying-with-odata) — filtering, sorting and paging.
- [Following links](/products/nowinfinity/resources/following-links) — using the `Links` array.
- [Accessing child accounts](/products/nowinfinity/resources/child-accounts) — the `X-NI-AccountID` header.