List received documents

GET

/api/integration/v1/inbound

Lists inbound documents, newest first.

With onlyNotImported=true only documents that have not been acknowledged yet are returned. Without the filter the acknowledged ones come back too, each with a visible ackedAt.

The example applies to the demo environment only.

Request

curl -i -X GET "https://sandbox.api.earhiva.mk/api/integration/v1/inbound" \
  -H "X-Api-Key: <YOUR KEY>" \
  -H "X-Software-Id: <NAME AND VERSION OF YOUR APPLICATION>"

Every call carries X-Api-Key with a key that has the IntegrationApi scope, and X-Software-Id with the name and version of your software. How to request a key is on Authentication.

Parameters

All parameters (8)

Parameter	In	Type	Presence	Description
dateFrom	query	string · date-time	optional	Lower bound on the time selected by by; omit for no lower bound. Inclusive.
dateTo	query	string · date-time	optional	Upper bound on the time selected by by; omit for no upper bound. Exclusive.
by	query	—	optional	What dateFrom and dateTo measure: created (default) is the time the document arrived, updated is the time we last recorded a change to it. Use updated to pull incrementally. It is not the same as onlyNotImported: that one asks what you have not fetched yet, this one asks what changed — a document you already fetched and that was then approved is returned only by updated. With updated the response also carries nextFrom.
senderEdb	query	string	optional	Tax number of the sender.
onlyNotImported	query	boolean	optional	When true, only documents without an acknowledgement.
page	query	integer · int32	optional	1-based page index; defaults to 1.
pageSize	query	integer · int32	optional	Documents per page; defaults to 100, maximum 500.
X-Software-Id	header	string	always	Identifier of the calling software, e.g. SSBFocus/4.2.1. Free text, recorded in the audit trail. Required on every call; missing means EARH-1008.

Error codes

EARH-1001 · EARH-1002 · EARH-1003 · EARH-1004 · EARH-1005 · EARH-1006 · EARH-1010 · EARH-1011 · EARH-3005

The full list of codes, what each means and what to do, is in the Error catalogue.

Responses

200

The page of documents; an empty result is 200 with totalCount 0.

{
  "items": [
    {
      "docUid": "eah_i_01M0ZZB88FT117S27PM8ZEK9RY",
      "receivedAt": "2026-08-26T09:12:04",
      "senderName": "Partner DOOEL Skopje",
      "senderEdb": "4080012600123",
      "ackedAt": null
    }
  ],
  "totalCount": 1,
  "page": 1,
  "pageSize": 100,
  "totalPages": 1
}

All fields in the body (6)

Field	Type	Presence	Description
items	array of object	always	Documents on the requested page, newest first.
totalCount	integer · int32	always	Number of documents matching the filter across all pages.
page	integer · int32	always	1-based index of the returned page.
pageSize	integer · int32	always	Number of documents per page (default 100, maximum 500).
totalPages	integer · int32	always	Number of pages available for the current filter and page size.
nextFrom	string · date-time	nullable	Starting point for your next incremental call: pass it back as dateFrom with by=updated. Returned only when you asked for by=updated, null otherwise. IT IS VALID ONLY AFTER YOU HAVE READ EVERY PAGE of this result — the list is ordered newest first, so a value taken after page 1 would skip every older change. The lower bound is inclusive and the value is deliberately set slightly in the past, so the next call will return some documents again; drop the repeats by docUid.

400

EARH-3005 — the requested page size exceeds the allowed one; the response names it.

{
  "type": "https://earhiva.mk/errors/EARH-3005",
  "title": "Requested page size exceeds the allowed maximum.",
  "status": 400,
  "code": "EARH-3005"
}

All fields in the body (6)

Field	Type	Presence	Description
type	string	always	Address of this code in the error catalogue (RFC 7807).
title	string	always	Short, stable English summary of the error — the same string that appears in your log.
status	integer · int32	always	HTTP status code, repeated in the body (RFC 7807).
detail	string	nullable	What went wrong in this particular call, when there is more to say than the title. Absent when the title already says everything.
code	string	always	The EARH-xxxx code. This is the contract: match on it, not on the text.
eventId	string	nullable	Only on EARH-9000. Quote it when reporting the problem — it is the same reference we record in our log, so one number identifies the event on both sides.

401

The API key is missing, unknown, expired or revoked — EARH-1001, EARH-1002, EARH-1003. The body is the standard error body — the same on every call. What to do about each code is in the Error catalogue.

403

The caller’s address is outside the allowed list, the key does not carry the IntegrationApi scope, the organization’s plan does not include integration access, or the key has been switched off by its owner — EARH-1004, EARH-1005, EARH-1010, EARH-1011. The last two are returned on every call and carry no Retry-After: waiting does not change the state. The body is the standard error body — the same on every call. What to do about each code is in the Error catalogue.

429

The traffic limit for this key has been reached — EARH-1006. The response carries Retry-After. The limit is counted per key, and its size comes from the organization’s plan. The body is the standard error body — the same on every call. What to do about each code is in the Error catalogue.

500

Unexpected error on our side — EARH-9000. The body carries eventId; quote it when reporting the problem. The body is the standard error body — the same on every call. What to do about each code is in the Error catalogue.