For developers

PODFY Open API reference

Fetch records, update their status and manage your reference register from your own systems. A JSON REST API, part of PODFY Advanced.

Download openapi.json ↓Ask about Advanced

What the API is

The PODFY Open API lets your own systems read records (proofs of delivery and QR reports), update their work status and manage the reference (asset) register. It is a JSON REST API for server to server use. There is no CORS: call it from your backend, never from a browser.

The Open API is part of PODFY Advanced. When it is not active for your brand, every call answers 403 feature_not_active. The specification is OpenAPI 3.1 and the reference below is generated from the same file.

Get an API key

A brand admin creates keys in the portal under Settings → Integrations → API keys. Give the key a name and choose its scopes. The key is shown once, so store it in your secrets manager. You can revoke a key at any time, and a revoked key stops working immediately.

records:read: read records
records:write: update records (also allows reading them)
references:read: read the reference register
references:write: create and change references (also allows reading them)

Base URL and authentication

The base URL is https://portal.podfy.net/api/v1. Send your key as a Bearer token in the Authorization header on every request. A key never works in a query parameter.

A missing, malformed, unknown or revoked key always gets the same answer, 401 invalid_key. A key without the required scope gets 403 insufficient_scope.

curl -H "Authorization: Bearer $PODFY_API_KEY" \
  "https://portal.podfy.net/api/v1/records?limit=10"

Live and test keys

Keys starting with pk_live_ see only production records. Keys starting with pk_test_ (QA records only) see only test records from qa.podfy.app, whose PODFY IDs start with QA-. The two environments never mix.

The reference register is shared with production, so test keys cannot create or change references (403 insufficient_scope). A record or reference of another brand, or a record of the other environment, answers 404 not_found, never 403.

Rate limit

Each key may make 600 requests per minute, counted in fixed one-minute windows. Every answer carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (unix seconds when the window ends).

Above the limit you get 429 rate_limited with a Retry-After header (seconds). Wait that long and try again.

Errors

Every error is JSON in the same shape: {"error":{"code":"…","message":"…"}}. Handle errors by the HTTP status and the code, not by the message text. Responses are never cached (Cache-Control: no-store). The full list of codes is in the reference below.

Pagination

List endpoints return {"data": [...], "next_cursor": "…"}. Pass next_cursor back as the cursor parameter to get the next page, until it is null. Cursors are opaque: do not build or change them. Records are listed newest first. The page size is set with limit (1 to 200, default 50).

Reference

Operations

The reference below is generated from the OpenAPI file and is in English in every language. Download the specification: openapi.json

Error codes

Status	Codes	Meaning
`400`	`invalid_parameter` `invalid_cursor` `invalid_body` `invalid_status` `invalid_priority` `invalid_assignee` `invalid_comment` `comment_too_long` `nothing_to_update` `invalid_ref` `name_too_long` `location_too_long` `group_code_too_long` `sticker_text_too_long` `no_valid_fields`	Invalid query parameter or body.
`401`	`invalid_key`	The API key is missing, malformed, unknown or revoked (always the same body).
`403`	`feature_not_active` `insufficient_scope`	The Open API (or, for references, the reference register; for record updates, status tracking) is not active for the brand, or the key lacks the scope.
`404`	`not_found`	No such endpoint, or no such record / reference for this key's brand and environment.
`405`	`method_not_allowed`	The endpoint exists but not with this method; `Allow` lists the methods.
`409`	`ref_exists`	The reference already exists.
`429`	`rate_limited`	More than 600 requests in this minute for this key.
`500`	`server_error`	Unexpected error; try again later.

GET `/records`

List records Required scope: records:read

Records of your brand, newest first. Deleted records are never listed.

Parameters

Name	In	Type	Required	Description
`since`	query	string	optional	Only records created at or after this moment (ISO 8601 date or date-time; a time without zone is UTC).
`updated_since`	query	string	optional	Only records changed (or created) at or after this moment (ISO 8601).
`status`	query	string	optional	Work status, one or more comma separated.
`reference`	query	string max 100 characters	optional	Exact reference (1-100 characters).
`category`	query	string max 40 characters	optional	Category code (letters, digits, _ and -; case-insensitive).
`limit`	query	integer 1-200 default 50	optional	Page size, 1-200 (default 50; larger values are capped at 200).
`cursor`	query	string	optional	The `next_cursor` of the previous page (opaque).

Response `200`

A page of records.

Field	Type	Required	Description
`data`	array of object	required
`data[].podfy_id`	string	required
`data[].mode`	string one of `delivery`, `report`	required
`data[].reference`	string	optional	Empty string when none.
`data[].asset`	object	optional	Register data at upload time.
`data[].asset.name`	string or null	optional
`data[].asset.location`	string or null	optional
`data[].asset.group`	string or null	optional
`data[].category`	string or null	optional	Category code (report mode) or delivery issue code.
`data[].priority`	string one of `low`, `normal`, `high`, `critical`	required
`data[].work_status`	string one of `new`, `in_progress`, `resolved`, `rejected`	required
`data[].note`	string	optional
`data[].fields`	object	optional	Custom form fields.
`data[].group_id`	string	required	Records of one multi-file upload share it (the podfy_id without the -N suffix).
`data[].files`	array of object	required
`data[].files[].name`	string	optional
`data[].files[].url`	string uri	optional
`data[].location`	object or null	optional
`data[].location.lat`	number	optional
`data[].location.lng`	number	optional
`data[].location.source`	string or null	optional
`data[].duplicate_of`	string or null	optional	podfy_id of the first report this one duplicates.
`data[].url`	string or null uri	optional	Public detail page of the record.
`data[].assignee`	string or null	optional	E-mail of the assigned brand member.
`data[].created_at`	string date-time	required
`data[].updated_at`	string or null date-time	optional
`data[].resolved_at`	string or null date-time	optional
`data[].keep_informed`	boolean	optional	True when the reporter asked to be kept informed (a confirmation or resolved message was or can be sent). Never the address.
`next_cursor`	string or null	required

Errors

Status	Codes	Meaning
`400`	`invalid_parameter` `invalid_cursor` `invalid_body` `invalid_status` `invalid_priority` `invalid_assignee` `invalid_comment` `comment_too_long` `nothing_to_update` `invalid_ref` `name_too_long` `location_too_long` `group_code_too_long` `sticker_text_too_long` `no_valid_fields`	Invalid query parameter or body.
`401`	`invalid_key`	The API key is missing, malformed, unknown or revoked (always the same body).
`403`	`feature_not_active` `insufficient_scope`	The Open API (or, for references, the reference register; for record updates, status tracking) is not active for the brand, or the key lacks the scope.
`404`	`not_found`	No such endpoint, or no such record / reference for this key's brand and environment.
`405`	`method_not_allowed`	The endpoint exists but not with this method; `Allow` lists the methods.
`429`	`rate_limited`	More than 600 requests in this minute for this key.
`500`	`server_error`	Unexpected error; try again later.

Example

curl \
  -H "Authorization: Bearer $PODFY_API_KEY" \
  "https://portal.podfy.net/api/v1/records?limit=50"

GET `/records/{podfy_id}`

Get a record Required scope: records:read

One record with its timeline (created, status, comment, assign, priority, duplicate). Mail recipients and reporter data never appear.

Parameters

Name	In	Type	Required	Description
`podfy_id`	path	string pattern `^[A-Za-z0-9_-]{1,64}$`	required	The record's PODFY ID, e.g. PFY-7Q4K2-1 (QA-… for test records).

Response `200`

The record.

Field	Type	Required	Description
`podfy_id`	string	required
`mode`	string one of `delivery`, `report`	required
`reference`	string	optional	Empty string when none.
`asset`	object	optional	Register data at upload time.
`asset.name`	string or null	optional
`asset.location`	string or null	optional
`asset.group`	string or null	optional
`category`	string or null	optional	Category code (report mode) or delivery issue code.
`priority`	string one of `low`, `normal`, `high`, `critical`	required
`work_status`	string one of `new`, `in_progress`, `resolved`, `rejected`	required
`note`	string	optional
`fields`	object	optional	Custom form fields.
`group_id`	string	required	Records of one multi-file upload share it (the podfy_id without the -N suffix).
`files`	array of object	required
`files[].name`	string	optional
`files[].url`	string uri	optional
`location`	object or null	optional
`location.lat`	number	optional
`location.lng`	number	optional
`location.source`	string or null	optional
`duplicate_of`	string or null	optional	podfy_id of the first report this one duplicates.
`url`	string or null uri	optional	Public detail page of the record.
`assignee`	string or null	optional	E-mail of the assigned brand member.
`created_at`	string date-time	required
`updated_at`	string or null date-time	optional
`resolved_at`	string or null date-time	optional
`keep_informed`	boolean	optional	True when the reporter asked to be kept informed (a confirmation or resolved message was or can be sent). Never the address.
`events`	array of object	required
`events[].type`	string one of `created`, `status`, `comment`, `assign`, `priority`, `duplicate`	required
`events[].from`	string or null	optional
`events[].to`	string or null	optional
`events[].note`	string or null	optional	The comment text (comment events only).
`events[].actor`	string or null	optional	Brand member e-mail, `app`, or `api:<key prefix>`.
`events[].created_at`	string date-time	required

Errors

Status	Codes	Meaning
`400`	`invalid_parameter` `invalid_cursor` `invalid_body` `invalid_status` `invalid_priority` `invalid_assignee` `invalid_comment` `comment_too_long` `nothing_to_update` `invalid_ref` `name_too_long` `location_too_long` `group_code_too_long` `sticker_text_too_long` `no_valid_fields`	Invalid query parameter or body.
`401`	`invalid_key`	The API key is missing, malformed, unknown or revoked (always the same body).
`403`	`feature_not_active` `insufficient_scope`	The Open API (or, for references, the reference register; for record updates, status tracking) is not active for the brand, or the key lacks the scope.
`404`	`not_found`	No such endpoint, or no such record / reference for this key's brand and environment.
`405`	`method_not_allowed`	The endpoint exists but not with this method; `Allow` lists the methods.
`429`	`rate_limited`	More than 600 requests in this minute for this key.
`500`	`server_error`	Unexpected error; try again later.

Example

curl \
  -H "Authorization: Bearer $PODFY_API_KEY" \
  "https://portal.podfy.net/api/v1/records/PFY-7Q4K2-1"

PATCH `/records/{podfy_id}`

Update a record Required scope: records:write

Change the work status, assignee or priority, or add a comment. Same rules as the portal: one timeline event per change, webhooks record.status_changed / record.updated are sent, the actor is api:<key prefix>. Needs status tracking (report mode or the status tracking add-on), else 403 feature_not_active. Only the fields below are accepted.

Parameters

Name	In	Type	Required	Description
`podfy_id`	path	string pattern `^[A-Za-z0-9_-]{1,64}$`	required	The record's PODFY ID, e.g. PFY-7Q4K2-1 (QA-… for test records).

Request body (JSON)

Field	Type	Required	Description
`work_status`	string one of `new`, `in_progress`, `resolved`, `rejected`	optional
`assignee`	string or null email	optional	An active member of the brand, or null to unassign.
`priority`	string one of `low`, `normal`, `high`, `critical`	optional
`comment`	string or null max 2000 characters	optional	Added to the timeline.

Response `200`

The record after the update. changed is false when nothing differed.

Field	Type	Required	Description
`changed`	boolean	required
`record`	object	required	The same record object as in webhook payloads, plus timestamps and the assignee.
`record.podfy_id`	string	required
`record.mode`	string one of `delivery`, `report`	required
`record.reference`	string	optional	Empty string when none.
`record.asset`	object	optional	Register data at upload time.
`record.asset.name`	string or null	optional
`record.asset.location`	string or null	optional
`record.asset.group`	string or null	optional
`record.category`	string or null	optional	Category code (report mode) or delivery issue code.
`record.priority`	string one of `low`, `normal`, `high`, `critical`	required
`record.work_status`	string one of `new`, `in_progress`, `resolved`, `rejected`	required
`record.note`	string	optional
`record.fields`	object	optional	Custom form fields.
`record.group_id`	string	required	Records of one multi-file upload share it (the podfy_id without the -N suffix).
`record.files`	array of object	required
`record.files[].name`	string	optional
`record.files[].url`	string uri	optional
`record.location`	object or null	optional
`record.location.lat`	number	optional
`record.location.lng`	number	optional
`record.location.source`	string or null	optional
`record.duplicate_of`	string or null	optional	podfy_id of the first report this one duplicates.
`record.url`	string or null uri	optional	Public detail page of the record.
`record.assignee`	string or null	optional	E-mail of the assigned brand member.
`record.created_at`	string date-time	required
`record.updated_at`	string or null date-time	optional
`record.resolved_at`	string or null date-time	optional
`record.keep_informed`	boolean	optional	True when the reporter asked to be kept informed (a confirmation or resolved message was or can be sent). Never the address.

Errors

Status	Codes	Meaning
`400`	`invalid_parameter` `invalid_cursor` `invalid_body` `invalid_status` `invalid_priority` `invalid_assignee` `invalid_comment` `comment_too_long` `nothing_to_update` `invalid_ref` `name_too_long` `location_too_long` `group_code_too_long` `sticker_text_too_long` `no_valid_fields`	Invalid query parameter or body.
`401`	`invalid_key`	The API key is missing, malformed, unknown or revoked (always the same body).
`403`	`feature_not_active` `insufficient_scope`	The Open API (or, for references, the reference register; for record updates, status tracking) is not active for the brand, or the key lacks the scope.
`404`	`not_found`	No such endpoint, or no such record / reference for this key's brand and environment.
`405`	`method_not_allowed`	The endpoint exists but not with this method; `Allow` lists the methods.
`429`	`rate_limited`	More than 600 requests in this minute for this key.
`500`	`server_error`	Unexpected error; try again later.

Example

curl -X PATCH \
  -H "Authorization: Bearer $PODFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"work_status": "in_progress", "assignee": "[email protected]"}' \
  "https://portal.podfy.net/api/v1/records/PFY-7Q4K2-1"

GET `/references`

List references Required scope: references:read

Your reference register, ordered by ref.

Parameters

Name	In	Type	Required	Description
`status`	query	string one of `active`, `retired`	optional
`group`	query	string max 40 characters	optional	Exact group code.
`q`	query	string max 100 characters	optional	Text contained in ref, name or location (1-100 characters).
`limit`	query	integer 1-200 default 50	optional	Page size, 1-200 (default 50; larger values are capped at 200).
`cursor`	query	string	optional	The `next_cursor` of the previous page (opaque).

Response `200`

A page of references.

Field	Type	Required	Description
`data`	array of object	required
`data[].ref`	string	required
`data[].kind`	string or null one of `asset`, `shipment`	optional
`data[].name`	string or null	optional
`data[].location`	string or null	optional
`data[].group_code`	string or null	optional
`data[].sticker_text`	string or null	optional
`data[].status`	string one of `active`, `retired`	required
`data[].active_from`	string or null	optional
`data[].retired_at`	string or null date-time	optional
`data[].created_at`	string or null date-time	optional
`data[].updated_at`	string or null date-time	optional
`data[].qr_url`	string uri	required	https://podfy.app/{brand}/{ref}
`next_cursor`	string or null	required

Errors

Status	Codes	Meaning
`400`	`invalid_parameter` `invalid_cursor` `invalid_body` `invalid_status` `invalid_priority` `invalid_assignee` `invalid_comment` `comment_too_long` `nothing_to_update` `invalid_ref` `name_too_long` `location_too_long` `group_code_too_long` `sticker_text_too_long` `no_valid_fields`	Invalid query parameter or body.
`401`	`invalid_key`	The API key is missing, malformed, unknown or revoked (always the same body).
`403`	`feature_not_active` `insufficient_scope`	The Open API (or, for references, the reference register; for record updates, status tracking) is not active for the brand, or the key lacks the scope.
`404`	`not_found`	No such endpoint, or no such record / reference for this key's brand and environment.
`405`	`method_not_allowed`	The endpoint exists but not with this method; `Allow` lists the methods.
`429`	`rate_limited`	More than 600 requests in this minute for this key.
`500`	`server_error`	Unexpected error; try again later.

Example

curl \
  -H "Authorization: Bearer $PODFY_API_KEY" \
  "https://portal.podfy.net/api/v1/references?limit=50"

POST `/references`

Create a reference Required scope: references:write

Adds one reference. 409 ref_exists when the ref is already in the register.

QA keys (pk_test_) cannot change references: the register is shared with production records (403 insufficient_scope).

Request body (JSON)

Field	Type	Required
`ref`	string pattern `^[A-Za-z0-9._-]{1,64}$`	required
`name`	string or null max 120 characters	optional
`location`	string or null max 120 characters	optional
`group_code`	string or null max 40 characters	optional
`sticker_text`	string or null max 120 characters	optional

Response `201`

The new reference.

Field	Type	Required	Description
`ref`	string	required
`kind`	string or null one of `asset`, `shipment`	optional
`name`	string or null	optional
`location`	string or null	optional
`group_code`	string or null	optional
`sticker_text`	string or null	optional
`status`	string one of `active`, `retired`	required
`active_from`	string or null	optional
`retired_at`	string or null date-time	optional
`created_at`	string or null date-time	optional
`updated_at`	string or null date-time	optional
`qr_url`	string uri	required	https://podfy.app/{brand}/{ref}

Errors

Status	Codes	Meaning
`400`	`invalid_parameter` `invalid_cursor` `invalid_body` `invalid_status` `invalid_priority` `invalid_assignee` `invalid_comment` `comment_too_long` `nothing_to_update` `invalid_ref` `name_too_long` `location_too_long` `group_code_too_long` `sticker_text_too_long` `no_valid_fields`	Invalid query parameter or body.
`401`	`invalid_key`	The API key is missing, malformed, unknown or revoked (always the same body).
`403`	`feature_not_active` `insufficient_scope`	The Open API (or, for references, the reference register; for record updates, status tracking) is not active for the brand, or the key lacks the scope.
`404`	`not_found`	No such endpoint, or no such record / reference for this key's brand and environment.
`405`	`method_not_allowed`	The endpoint exists but not with this method; `Allow` lists the methods.
`409`	`ref_exists`	The reference already exists.
`429`	`rate_limited`	More than 600 requests in this minute for this key.
`500`	`server_error`	Unexpected error; try again later.

Example

curl -X POST \
  -H "Authorization: Bearer $PODFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ref": "example", "name": "example"}' \
  "https://portal.podfy.net/api/v1/references"

GET `/references/{ref}`

Get a reference Required scope: references:read

One reference.

Parameters

Name	In	Type	Required	Description
`ref`	path	string pattern `^[A-Za-z0-9._-]{1,64}$`	required	The reference (1-64 characters: letters, digits, dot, underscore, hyphen).

Response `200`

The reference.

Field	Type	Required	Description
`ref`	string	required
`kind`	string or null one of `asset`, `shipment`	optional
`name`	string or null	optional
`location`	string or null	optional
`group_code`	string or null	optional
`sticker_text`	string or null	optional
`status`	string one of `active`, `retired`	required
`active_from`	string or null	optional
`retired_at`	string or null date-time	optional
`created_at`	string or null date-time	optional
`updated_at`	string or null date-time	optional
`qr_url`	string uri	required	https://podfy.app/{brand}/{ref}

Errors

Status	Codes	Meaning
`400`	`invalid_parameter` `invalid_cursor` `invalid_body` `invalid_status` `invalid_priority` `invalid_assignee` `invalid_comment` `comment_too_long` `nothing_to_update` `invalid_ref` `name_too_long` `location_too_long` `group_code_too_long` `sticker_text_too_long` `no_valid_fields`	Invalid query parameter or body.
`401`	`invalid_key`	The API key is missing, malformed, unknown or revoked (always the same body).
`403`	`feature_not_active` `insufficient_scope`	The Open API (or, for references, the reference register; for record updates, status tracking) is not active for the brand, or the key lacks the scope.
`404`	`not_found`	No such endpoint, or no such record / reference for this key's brand and environment.
`405`	`method_not_allowed`	The endpoint exists but not with this method; `Allow` lists the methods.
`429`	`rate_limited`	More than 600 requests in this minute for this key.
`500`	`server_error`	Unexpected error; try again later.

Example

curl \
  -H "Authorization: Bearer $PODFY_API_KEY" \
  "https://portal.podfy.net/api/v1/references/YOUR_REF"

PATCH `/references/{ref}`

Update a reference Required scope: references:write

Edit, move, retire (status: retired) or reactivate a reference. Only the fields below are accepted; an empty string clears a text field.

QA keys (pk_test_) cannot change references: the register is shared with production records (403 insufficient_scope).

Parameters

Name	In	Type	Required	Description
`ref`	path	string pattern `^[A-Za-z0-9._-]{1,64}$`	required	The reference (1-64 characters: letters, digits, dot, underscore, hyphen).

Request body (JSON)

Field	Type	Required
`name`	string or null max 120 characters	optional
`location`	string or null max 120 characters	optional
`group_code`	string or null max 40 characters	optional
`sticker_text`	string or null max 120 characters	optional
`status`	string one of `active`, `retired`	optional

Response `200`

The reference after the update.

Field	Type	Required	Description
`changed`	boolean	required
`reference`	object	required
`reference.ref`	string	required
`reference.kind`	string or null one of `asset`, `shipment`	optional
`reference.name`	string or null	optional
`reference.location`	string or null	optional
`reference.group_code`	string or null	optional
`reference.sticker_text`	string or null	optional
`reference.status`	string one of `active`, `retired`	required
`reference.active_from`	string or null	optional
`reference.retired_at`	string or null date-time	optional
`reference.created_at`	string or null date-time	optional
`reference.updated_at`	string or null date-time	optional
`reference.qr_url`	string uri	required	https://podfy.app/{brand}/{ref}

Errors

Status	Codes	Meaning
`400`	`invalid_parameter` `invalid_cursor` `invalid_body` `invalid_status` `invalid_priority` `invalid_assignee` `invalid_comment` `comment_too_long` `nothing_to_update` `invalid_ref` `name_too_long` `location_too_long` `group_code_too_long` `sticker_text_too_long` `no_valid_fields`	Invalid query parameter or body.
`401`	`invalid_key`	The API key is missing, malformed, unknown or revoked (always the same body).
`403`	`feature_not_active` `insufficient_scope`	The Open API (or, for references, the reference register; for record updates, status tracking) is not active for the brand, or the key lacks the scope.
`404`	`not_found`	No such endpoint, or no such record / reference for this key's brand and environment.
`405`	`method_not_allowed`	The endpoint exists but not with this method; `Allow` lists the methods.
`429`	`rate_limited`	More than 600 requests in this minute for this key.
`500`	`server_error`	Unexpected error; try again later.

Example

curl -X PATCH \
  -H "Authorization: Bearer $PODFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "example", "location": "example"}' \
  "https://portal.podfy.net/api/v1/references/YOUR_REF"

PODFY Open API reference

What the API is

Get an API key

Base URL and authentication

Live and test keys

Rate limit

Errors

Pagination

Operations

Error codes

GET /records

Parameters

Response 200

Errors

Example

GET /records/{podfy_id}

Parameters

Response 200

Errors

Example

PATCH /records/{podfy_id}

Parameters

Request body (JSON)

Response 200

Errors

Example

GET /references

Parameters

Response 200

Errors

Example

POST /references

Request body (JSON)

Response 201

Errors

Example

GET /references/{ref}

Parameters

Response 200

Errors

Example

PATCH /references/{ref}

Parameters

Request body (JSON)

Response 200

Errors

Example

GET `/records`

Response `200`

GET `/records/{podfy_id}`

Response `200`

PATCH `/records/{podfy_id}`

Response `200`

GET `/references`

Response `200`

POST `/references`

Response `201`

GET `/references/{ref}`

Response `200`

PATCH `/references/{ref}`

Response `200`