De referentie hieronder is gegenereerd uit het OpenAPI-bestand en staat in elke taal in het Engels. Download de specificatie: openapi.json
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 | Description |
|---|
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
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 | Description |
|---|
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"