A File is an entity that can store a physical file and some metadata. It also provides an easy access to its size, mime-type, user-defined tags and description thus allowing easy sorting and searching among stored files. There are several methods of file uploading available: multipart/form-data encoded form, RAW POST (by sending file contents as POST body), fetching from URL (by providing the file URL via 'url' param) Attachment is an entity that is used to link a File to one or multiple objects like Customer, Dispute, Payment, Transaction, Order, Plan, Product, Invoice, Note. That allows to quickly find and use files related to those specific entities.
Retrieve a list of attachments. You may sort by the id, name, relatedId, relatedType, fileId, createdTime, and updatedTime.
limit | integer [ 0 .. 1000 ] The collection items limit. |
offset | integer >= 0 The collection items offset. |
filter | string The collection items filter requires a special format. Use "," for multiple allowed values. Use ";" for multiple fields. See the filter guide for more options and examples about this format. |
q | string The partial search of the text fields. |
expand | string Expand a response to get a full related object included inside of the |
fields | string Limit the returned fields to the list specified, separated by comma. Note that id is always returned. |
sort | Array of strings The collection items sort field and order (prefix with "-" for descending sort). |
A list of Attachments was retrieved successfully.
Pagination-Total | integer Total items count. |
Pagination-Limit | integer Items per page limit. |
Pagination-Offset | integer Pagination offset. |
Unauthorized access, invalid credentials were used.
Access forbidden.
$attachments = $client->attachments()->search([ 'filter' => 'relatedType:customer', ]);
[- {
- "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
- "fileId": "string",
- "relatedType": "customer",
- "relatedId": "string",
- "name": "string",
- "description": "string",
- "createdTime": "2019-08-24T14:15:22Z",
- "updatedTime": "2019-08-24T14:15:22Z",
- "_links": [
- {
- "rel": "self",
- "href": "string"
}, - {
- "rel": "self",
- "href": "string"
}, - {
- "rel": "self",
- "href": "string"
}
], - "_embedded": [
- {
- "file": {
- "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
- "name": "string",
- "extension": "string",
- "description": "string",
- "sourceType": "upload",
- "tags": [
- "string"
], - "mime": "image/png",
- "size": 0,
- "width": 0,
- "height": 0,
- "sha1": "string",
- "createdTime": "2019-08-24T14:15:22Z",
- "updatedTime": "2019-08-24T14:15:22Z",
- "isPublic": true,
- "_links": [
- {
- "rel": "self",
- "href": "string"
}, - {
- "rel": "self",
- "href": "string"
}, - {
- "rel": "self",
- "href": "string"
}
]
}
}
]
}
]
Create an Attachment.
Attachment resource.
fileId required | string Linked File object id. |
relatedId required | string Linked object Id. |
relatedType required | string Linked object type. |
name | string The Original Attachment name. |
description | string The Attachment description. |
Attachment was created.
fileId required | string Linked File object id. | ||
relatedId required | string Linked object Id. | ||
relatedType required | string Linked object type. | ||
id | string <= 50 characters The resource ID. Defaults to UUID v4. | ||
name | string The Original Attachment name. | ||
description | string The Attachment description. | ||
createdTime | string <date-time> Read-only timestamp, automatically assigned on back-end. | ||
updatedTime | string <date-time> Read-only timestamp, automatically assigned on back-end. | ||
Array of SelfLink (object) or FileLink (object) or AttachmentResourceLink (object) >= 3 items The links related to resource. | |||
Array of FileEmbed (object) non-empty Any embedded objects available that are requested by the | |||
Array (non-empty) Any of: File object.
|
Unauthorized access, invalid credentials were used.
Access forbidden.
Conflict.
Invalid data was sent.
{- "fileId": "string",
- "relatedType": "customer",
- "relatedId": "string",
- "name": "string",
- "description": "string"
}
{- "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
- "fileId": "string",
- "relatedType": "customer",
- "relatedId": "string",
- "name": "string",
- "description": "string",
- "createdTime": "2019-08-24T14:15:22Z",
- "updatedTime": "2019-08-24T14:15:22Z",
- "_links": [
- {
- "rel": "self",
- "href": "string"
}, - {
- "rel": "self",
- "href": "string"
}, - {
- "rel": "self",
- "href": "string"
}
], - "_embedded": [
- {
- "file": {
- "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
- "name": "string",
- "extension": "string",
- "description": "string",
- "sourceType": "upload",
- "tags": [
- "string"
], - "mime": "image/png",
- "size": 0,
- "width": 0,
- "height": 0,
- "sha1": "string",
- "createdTime": "2019-08-24T14:15:22Z",
- "updatedTime": "2019-08-24T14:15:22Z",
- "isPublic": true,
- "_links": [
- {
- "rel": "self",
- "href": "string"
}, - {
- "rel": "self",
- "href": "string"
}, - {
- "rel": "self",
- "href": "string"
}
]
}
}
]
}
Retrieve a Attachment with specified identifier string.
Attachment was retrieved successfully.
fileId required | string Linked File object id. | ||
relatedId required | string Linked object Id. | ||
relatedType required | string Linked object type. | ||
id | string <= 50 characters The resource ID. Defaults to UUID v4. | ||
name | string The Original Attachment name. | ||
description | string The Attachment description. | ||
createdTime | string <date-time> Read-only timestamp, automatically assigned on back-end. | ||
updatedTime | string <date-time> Read-only timestamp, automatically assigned on back-end. | ||
Array of SelfLink (object) or FileLink (object) or AttachmentResourceLink (object) >= 3 items The links related to resource. | |||
Array of FileEmbed (object) non-empty Any embedded objects available that are requested by the | |||
Array (non-empty) Any of: File object.
|
Unauthorized access, invalid credentials were used.
Access forbidden.
Resource was not found.
$attachment = $client->attachments()->load('attachmentId');
{- "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
- "fileId": "string",
- "relatedType": "customer",
- "relatedId": "string",
- "name": "string",
- "description": "string",
- "createdTime": "2019-08-24T14:15:22Z",
- "updatedTime": "2019-08-24T14:15:22Z",
- "_links": [
- {
- "rel": "self",
- "href": "string"
}, - {
- "rel": "self",
- "href": "string"
}, - {
- "rel": "self",
- "href": "string"
}
], - "_embedded": [
- {
- "file": {
- "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
- "name": "string",
- "extension": "string",
- "description": "string",
- "sourceType": "upload",
- "tags": [
- "string"
], - "mime": "image/png",
- "size": 0,
- "width": 0,
- "height": 0,
- "sha1": "string",
- "createdTime": "2019-08-24T14:15:22Z",
- "updatedTime": "2019-08-24T14:15:22Z",
- "isPublic": true,
- "_links": [
- {
- "rel": "self",
- "href": "string"
}, - {
- "rel": "self",
- "href": "string"
}, - {
- "rel": "self",
- "href": "string"
}
]
}
}
]
}
Update the Attachment with predefined ID.
Attachment resource.
fileId required | string Linked File object id. |
relatedId required | string Linked object Id. |
relatedType required | string Linked object type. |
name | string The Original Attachment name. |
description | string The Attachment description. |
Attachment was updated.
fileId required | string Linked File object id. | ||
relatedId required | string Linked object Id. | ||
relatedType required | string Linked object type. | ||
id | string <= 50 characters The resource ID. Defaults to UUID v4. | ||
name | string The Original Attachment name. | ||
description | string The Attachment description. | ||
createdTime | string <date-time> Read-only timestamp, automatically assigned on back-end. | ||
updatedTime | string <date-time> Read-only timestamp, automatically assigned on back-end. | ||
Array of SelfLink (object) or FileLink (object) or AttachmentResourceLink (object) >= 3 items The links related to resource. | |||
Array of FileEmbed (object) non-empty Any embedded objects available that are requested by the | |||
Array (non-empty) Any of: File object.
|
Attachment was created.
fileId required | string Linked File object id. | ||
relatedId required | string Linked object Id. | ||
relatedType required | string Linked object type. | ||
id | string <= 50 characters The resource ID. Defaults to UUID v4. | ||
name | string The Original Attachment name. | ||
description | string The Attachment description. | ||
createdTime | string <date-time> Read-only timestamp, automatically assigned on back-end. | ||
updatedTime | string <date-time> Read-only timestamp, automatically assigned on back-end. | ||
Array of SelfLink (object) or FileLink (object) or AttachmentResourceLink (object) >= 3 items The links related to resource. | |||
Array of FileEmbed (object) non-empty Any embedded objects available that are requested by the | |||
Array (non-empty) Any of: File object.
|
Unauthorized access, invalid credentials were used.
Access forbidden.
Resource was not found.
Conflict.
Invalid data was sent.
{- "fileId": "string",
- "relatedType": "customer",
- "relatedId": "string",
- "name": "string",
- "description": "string"
}
{- "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
- "fileId": "string",
- "relatedType": "customer",
- "relatedId": "string",
- "name": "string",
- "description": "string",
- "createdTime": "2019-08-24T14:15:22Z",
- "updatedTime": "2019-08-24T14:15:22Z",
- "_links": [
- {
- "rel": "self",
- "href": "string"
}, - {
- "rel": "self",
- "href": "string"
}, - {
- "rel": "self",
- "href": "string"
}
], - "_embedded": [
- {
- "file": {
- "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
- "name": "string",
- "extension": "string",
- "description": "string",
- "sourceType": "upload",
- "tags": [
- "string"
], - "mime": "image/png",
- "size": 0,
- "width": 0,
- "height": 0,
- "sha1": "string",
- "createdTime": "2019-08-24T14:15:22Z",
- "updatedTime": "2019-08-24T14:15:22Z",
- "isPublic": true,
- "_links": [
- {
- "rel": "self",
- "href": "string"
}, - {
- "rel": "self",
- "href": "string"
}, - {
- "rel": "self",
- "href": "string"
}
]
}
}
]
}
Delete the Attachment with predefined identifier string.
Attachment was deleted.
Unauthorized access, invalid credentials were used.
Resource was not found.
$client->attachments()->delete('attachmentId');
{- "status": 401,
- "title": "string",
- "detail": "string",
- "instance": "string"
}
Retrieve a list of files.
limit | integer [ 0 .. 1000 ] The collection items limit. |
offset | integer >= 0 The collection items offset. |
filter | string The collection items filter requires a special format. Use "," for multiple allowed values. Use ";" for multiple fields. See the filter guide for more options and examples about this format. |
q | string The partial search of the text fields. |
expand | string Expand a response to get a full related object included inside of the |
fields | string Limit the returned fields to the list specified, separated by comma. Note that id is always returned. |
sort | Array of strings The collection items sort field and order (prefix with "-" for descending sort). |
A list of Files was retrieved successfully.
Pagination-Total | integer Total items count. |
Pagination-Limit | integer Items per page limit. |
Pagination-Offset | integer Pagination offset. |
id | string <= 50 characters The resource ID. Defaults to UUID v4. |
name | string Original File name. |
extension | string The File extension. |
description | string The File description. |
sourceType | string or null The File source type. |
tags | Array of strings The tags list. |
mime | string The mime type. |
size | integer The File size in bytes. |
width | integer Image width, applicable to images only. |
height | integer Image height, applicable to images only. |
sha1 | string Hash sum of the file. |
createdTime | string <date-time> Read-only timestamp, automatically assigned on back-end. |
updatedTime | string <date-time> Read-only timestamp, automatically assigned on back-end. |
isPublic | boolean Is the file available publicly (without authentication). If true, the permalink in the _links section contains the public URL. |
Array of SelfLink (object) or FileDownloadLink (object) or SignedLinkLink (object) or PermalinkLink (object) >= 3 items The links related to resource. | |
Unauthorized access, invalid credentials were used.
Access forbidden.
$files = $client->files()->search([ 'filter' => 'name:TestFile', ]);
[- {
- "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
- "name": "string",
- "extension": "string",
- "description": "string",
- "sourceType": "upload",
- "tags": [
- "string"
], - "mime": "image/png",
- "size": 0,
- "width": 0,
- "height": 0,
- "sha1": "string",
- "createdTime": "2019-08-24T14:15:22Z",
- "updatedTime": "2019-08-24T14:15:22Z",
- "isPublic": true,
- "_links": [
- {
- "rel": "self",
- "href": "string"
}, - {
- "rel": "self",
- "href": "string"
}, - {
- "rel": "self",
- "href": "string"
}
]
}
]
Additionally, a file can be sent with:.
file
is an uploaded file)Content-Type
. No additional
properties can be set along the request dataThe following file types only are allowed:
If using a Publishable Api Key, only private files can be created. The files can later on be modified or used using a secret API key.
file required | string The file in base64 encoded format. |
isPublic | boolean The File visibility. If public a permalink is provided. |
name | string The file name used for downloading. |
description | string The file description. |
sourceType | string or null The File source type. |
tags | Array of strings The tags list. |
File was created.
id | string <= 50 characters The resource ID. Defaults to UUID v4. |
name | string Original File name. |
extension | string The File extension. |
description | string The File description. |
sourceType | string or null The File source type. |
tags | Array of strings The tags list. |
mime | string The mime type. |
size | integer The File size in bytes. |
width | integer Image width, applicable to images only. |
height | integer Image height, applicable to images only. |
sha1 | string Hash sum of the file. |
createdTime | string <date-time> Read-only timestamp, automatically assigned on back-end. |
updatedTime | string <date-time> Read-only timestamp, automatically assigned on back-end. |
isPublic | boolean Is the file available publicly (without authentication). If true, the permalink in the _links section contains the public URL. |
Array of SelfLink (object) or FileDownloadLink (object) or SignedLinkLink (object) or PermalinkLink (object) >= 3 items The links related to resource. | |
Unauthorized access, invalid credentials were used.
Access forbidden.
Invalid data was sent.
{- "file": "R0lGODlhAQABAIAAAAUEBAAAACwAAAAAAQABAAACAkQBADs=",
- "isPublic": false,
- "name": "logo.png",
- "description": "My file description",
- "sourceType": "upload",
- "tags": [
- "test",
- "tags"
]
}
{- "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
- "name": "string",
- "extension": "string",
- "description": "string",
- "sourceType": "upload",
- "tags": [
- "string"
], - "mime": "image/png",
- "size": 0,
- "width": 0,
- "height": 0,
- "sha1": "string",
- "createdTime": "2019-08-24T14:15:22Z",
- "updatedTime": "2019-08-24T14:15:22Z",
- "isPublic": true,
- "_links": [
- {
- "rel": "self",
- "href": "string"
}, - {
- "rel": "self",
- "href": "string"
}, - {
- "rel": "self",
- "href": "string"
}
]
}
Retrieve a File with specified identifier string.
File was retrieved successfully.
id | string <= 50 characters The resource ID. Defaults to UUID v4. |
name | string Original File name. |
extension | string The File extension. |
description | string The File description. |
sourceType | string or null The File source type. |
tags | Array of strings The tags list. |
mime | string The mime type. |
size | integer The File size in bytes. |
width | integer Image width, applicable to images only. |
height | integer Image height, applicable to images only. |
sha1 | string Hash sum of the file. |
createdTime | string <date-time> Read-only timestamp, automatically assigned on back-end. |
updatedTime | string <date-time> Read-only timestamp, automatically assigned on back-end. |
isPublic | boolean Is the file available publicly (without authentication). If true, the permalink in the _links section contains the public URL. |
Array of SelfLink (object) or FileDownloadLink (object) or SignedLinkLink (object) or PermalinkLink (object) >= 3 items The links related to resource. | |
Unauthorized access, invalid credentials were used.
Access forbidden.
Resource was not found.
$file = $client->files()->load('fileId');
{- "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
- "name": "string",
- "extension": "string",
- "description": "string",
- "sourceType": "upload",
- "tags": [
- "string"
], - "mime": "image/png",
- "size": 0,
- "width": 0,
- "height": 0,
- "sha1": "string",
- "createdTime": "2019-08-24T14:15:22Z",
- "updatedTime": "2019-08-24T14:15:22Z",
- "isPublic": true,
- "_links": [
- {
- "rel": "self",
- "href": "string"
}, - {
- "rel": "self",
- "href": "string"
}, - {
- "rel": "self",
- "href": "string"
}
]
}
Update the File with predefined ID. Note that file can be uploaded with POST. only.
File resource.
name | string Original File name. |
extension | string The File extension. |
description | string The File description. |
sourceType | string or null The File source type. |
tags | Array of strings The tags list. |
isPublic | boolean Is the file available publicly (without authentication). If true, the permalink in the _links section contains the public URL. |
File was updated.
id | string <= 50 characters The resource ID. Defaults to UUID v4. |
name | string Original File name. |
extension | string The File extension. |
description | string The File description. |
sourceType | string or null The File source type. |
tags | Array of strings The tags list. |
mime | string The mime type. |
size | integer The File size in bytes. |
width | integer Image width, applicable to images only. |
height | integer Image height, applicable to images only. |
sha1 | string Hash sum of the file. |
createdTime | string <date-time> Read-only timestamp, automatically assigned on back-end. |
updatedTime | string <date-time> Read-only timestamp, automatically assigned on back-end. |
isPublic | boolean Is the file available publicly (without authentication). If true, the permalink in the _links section contains the public URL. |
Array of SelfLink (object) or FileDownloadLink (object) or SignedLinkLink (object) or PermalinkLink (object) >= 3 items The links related to resource. | |
Unauthorized access, invalid credentials were used.
Access forbidden.
Resource was not found.
Invalid data was sent.
{- "name": "string",
- "extension": "string",
- "description": "string",
- "sourceType": "upload",
- "tags": [
- "string"
], - "isPublic": true
}
{- "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
- "name": "string",
- "extension": "string",
- "description": "string",
- "sourceType": "upload",
- "tags": [
- "string"
], - "mime": "image/png",
- "size": 0,
- "width": 0,
- "height": 0,
- "sha1": "string",
- "createdTime": "2019-08-24T14:15:22Z",
- "updatedTime": "2019-08-24T14:15:22Z",
- "isPublic": true,
- "_links": [
- {
- "rel": "self",
- "href": "string"
}, - {
- "rel": "self",
- "href": "string"
}, - {
- "rel": "self",
- "href": "string"
}
]
}
Delete the File with predefined identifier string.
File was deleted.
Unauthorized access, invalid credentials were used.
Access forbidden.
Resource was not found.
$client->files()->delete('fileId');
{- "status": 401,
- "title": "string",
- "detail": "string",
- "instance": "string"
}
Download a file.
imageSize | string^[1-9]{1}[0-9]{1,3}x[1-9]{1}[0-9]{1,3}$ Resize image to specified size. Supports any sizes from 10x10 to 2000x2000 (format Example: imageSize=700x700 |
The file was retrieved successfully.
Resource was moved.
Unauthorized access, invalid credentials were used.
Access forbidden.
Resource was not found.
const file = await api.files.download({id: 'my-file-id'}); // access the file ArrayBuffer to view the content console.log(file.data);
"string"