Files

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

Retrieve a list of attachments. You may sort by the id, name, relatedId, relatedType, fileId, createdTime, and updatedTime.

Request
Security:
query Parameters
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 _embedded path in the response. It accepts a comma-separated list of objects to expand. See the expand guide for more info.

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).

header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
200A list of Attachments was retrieved successfully.
Response Headers
Pagination-Total
integer

Total items count.

Pagination-Limit
integer

Items per page limit.

Pagination-Offset
integer

Pagination offset.

Response Schema: application/json
Array
id
string <= 50 characters

The resource ID. Defaults to UUID v4.

fileId
required
string

Linked File object id.

relatedType
required
string

Linked object type.

Enum: "customer" "dispute" "gateway-timeline-comment" "invoice" "organization" "payment" "plan" "product" "subscription" "transaction" "customer-timeline-comment" "transaction-timeline-comment" "order-timeline-comment"
relatedId
required
string

Linked object Id.

name
string

The Original Attachment name.

description
string

The Attachment description.

createdTime
string <date-time>

Creation date/time.

updatedTime
string <date-time>

Latest update date/time.

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 expand querystring parameter.

401Unauthorized access, invalid credentials was used.
403Access forbidden.
get/attachments
Request samples
$attachments = $client->attachments()->search([
    'filter' => 'relatedType:customer',
]);
Response samples
application/json
[
  • {
    }
]

Create an Attachment

Create an Attachment.

Request
Security:
header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Request Body schema: application/json

Attachment resource.

fileId
required
string

Linked File object id.

relatedType
required
string

Linked object type.

Enum: "customer" "dispute" "gateway-timeline-comment" "invoice" "organization" "payment" "plan" "product" "subscription" "transaction" "customer-timeline-comment" "transaction-timeline-comment" "order-timeline-comment"
relatedId
required
string

Linked object Id.

name
string

The Original Attachment name.

description
string

The Attachment description.

Responses
201Attachment was created.
Response Schema: application/json
id
string <= 50 characters

The resource ID. Defaults to UUID v4.

fileId
required
string

Linked File object id.

relatedType
required
string

Linked object type.

Enum: "customer" "dispute" "gateway-timeline-comment" "invoice" "organization" "payment" "plan" "product" "subscription" "transaction" "customer-timeline-comment" "transaction-timeline-comment" "order-timeline-comment"
relatedId
required
string

Linked object Id.

name
string

The Original Attachment name.

description
string

The Attachment description.

createdTime
string <date-time>

Creation date/time.

updatedTime
string <date-time>

Latest update date/time.

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 expand querystring parameter.

401Unauthorized access, invalid credentials was used.
403Access forbidden.
409Conflict.
422Invalid data was sent.
post/attachments
Request samples
application/json
{
  • "fileId": "string",
  • "relatedType": "customer",
  • "relatedId": "string",
  • "name": "string",
  • "description": "string"
}
Response samples
application/json
{
  • "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": [
    ],
  • "_embedded": [
    ]
}

Retrieve an Attachment

Retrieve a Attachment with specified identifier string.

Request
Security:
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
200Attachment was retrieved successfully.
Response Schema: application/json
id
string <= 50 characters

The resource ID. Defaults to UUID v4.

fileId
required
string

Linked File object id.

relatedType
required
string

Linked object type.

Enum: "customer" "dispute" "gateway-timeline-comment" "invoice" "organization" "payment" "plan" "product" "subscription" "transaction" "customer-timeline-comment" "transaction-timeline-comment" "order-timeline-comment"
relatedId
required
string

Linked object Id.

name
string

The Original Attachment name.

description
string

The Attachment description.

createdTime
string <date-time>

Creation date/time.

updatedTime
string <date-time>

Latest update date/time.

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 expand querystring parameter.

401Unauthorized access, invalid credentials was used.
403Access forbidden.
404Resource was not found.
get/attachments/{id}
Request samples
$attachment = $client->attachments()->load('attachmentId');
Response samples
application/json
{
  • "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": [
    ],
  • "_embedded": [
    ]
}

Update the Attachment with predefined ID

Update the Attachment with predefined ID.

Request
Security:
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Request Body schema: application/json

Attachment resource.

fileId
required
string

Linked File object id.

relatedType
required
string

Linked object type.

Enum: "customer" "dispute" "gateway-timeline-comment" "invoice" "organization" "payment" "plan" "product" "subscription" "transaction" "customer-timeline-comment" "transaction-timeline-comment" "order-timeline-comment"
relatedId
required
string

Linked object Id.

name
string

The Original Attachment name.

description
string

The Attachment description.

Responses
200Attachment was updated.
Response Schema: application/json
id
string <= 50 characters

The resource ID. Defaults to UUID v4.

fileId
required
string

Linked File object id.

relatedType
required
string

Linked object type.

Enum: "customer" "dispute" "gateway-timeline-comment" "invoice" "organization" "payment" "plan" "product" "subscription" "transaction" "customer-timeline-comment" "transaction-timeline-comment" "order-timeline-comment"
relatedId
required
string

Linked object Id.

name
string

The Original Attachment name.

description
string

The Attachment description.

createdTime
string <date-time>

Creation date/time.

updatedTime
string <date-time>

Latest update date/time.

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 expand querystring parameter.

201Attachment was created.
Response Schema: application/json
id
string <= 50 characters

The resource ID. Defaults to UUID v4.

fileId
required
string

Linked File object id.

relatedType
required
string

Linked object type.

Enum: "customer" "dispute" "gateway-timeline-comment" "invoice" "organization" "payment" "plan" "product" "subscription" "transaction" "customer-timeline-comment" "transaction-timeline-comment" "order-timeline-comment"
relatedId
required
string

Linked object Id.

name
string

The Original Attachment name.

description
string

The Attachment description.

createdTime
string <date-time>

Creation date/time.

updatedTime
string <date-time>

Latest update date/time.

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 expand querystring parameter.

401Unauthorized access, invalid credentials was used.
403Access forbidden.
404Resource was not found.
409Conflict.
422Invalid data was sent.
put/attachments/{id}
Request samples
application/json
{
  • "fileId": "string",
  • "relatedType": "customer",
  • "relatedId": "string",
  • "name": "string",
  • "description": "string"
}
Response samples
application/json
{
  • "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": [
    ],
  • "_embedded": [
    ]
}

Delete an Attachment

Delete the Attachment with predefined identifier string.

Request
Security:
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
204Attachment was deleted.
401Unauthorized access, invalid credentials was used.
404Resource was not found.
delete/attachments/{id}
Request samples
$client->attachments()->delete('attachmentId');
Response samples
application/json
{
  • "status": 400,
  • "title": "string",
  • "detail": "string",
  • "error": "string"
}

Retrieve a list of files

Retrieve a list of files.

Request
Security:
query Parameters
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 _embedded path in the response. It accepts a comma-separated list of objects to expand. See the expand guide for more info.

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).

header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
200A list of Files was retrieved successfully.
Response Headers
Pagination-Total
integer

Total items count.

Pagination-Limit
integer

Items per page limit.

Pagination-Offset
integer

Pagination offset.

Response Schema: application/json
Array
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.

tags
Array of strings

The tags list.

mime
string

The mime type.

Enum: "image/png" "image/jpeg" "image/gif" "application/pdf" "audio/mpeg"
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>

The upload date/time.

updatedTime
string <date-time>

The latest update date/time.

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.

401Unauthorized access, invalid credentials was used.
403Access forbidden.
get/files
Request samples
$files = $client->files()->search([
    'filter' => 'name:TestFile',
]);
Response samples
application/json
[
  • {
    }
]

Create a file

Additionally, a file can be sent with:.

  • multipart/form-data POST request: in this case all property names are the same as the JSON ones (file is an uploaded file)
  • file body request: the file body is sent as the request body, with the appropriate Content-Type. No additional properties can be set along the request data

The following file types only are allowed:

  • jpg
  • png
  • gif
  • pdf
  • mp3

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.

Request
header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Request Body schema: application/json
One of:
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.

tags
Array of strings

The tags list.

Responses
201File was created.
Response Schema: application/json
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.

tags
Array of strings

The tags list.

mime
string

The mime type.

Enum: "image/png" "image/jpeg" "image/gif" "application/pdf" "audio/mpeg"
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>

The upload date/time.

updatedTime
string <date-time>

The latest update date/time.

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.

401Unauthorized access, invalid credentials was used.
403Access forbidden.
422Invalid data was sent.
post/files
Request samples
application/json
{
  • "file": "R0lGODlhAQABAIAAAAUEBAAAACwAAAAAAQABAAACAkQBADs=",
  • "isPublic": false,
  • "name": "logo.png",
  • "description": "My file description",
  • "tags": [
    ]
}
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "name": "string",
  • "extension": "string",
  • "description": "string",
  • "tags": [
    ],
  • "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": [
    ]
}

Retrieve a File Record

Retrieve a File with specified identifier string.

Request
Security:
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
200File was retrieved successfully.
Response Schema: application/json
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.

tags
Array of strings

The tags list.

mime
string

The mime type.

Enum: "image/png" "image/jpeg" "image/gif" "application/pdf" "audio/mpeg"
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>

The upload date/time.

updatedTime
string <date-time>

The latest update date/time.

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.

401Unauthorized access, invalid credentials was used.
403Access forbidden.
404Resource was not found.
get/files/{id}
Request samples
$file = $client->files()->load('fileId');
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "name": "string",
  • "extension": "string",
  • "description": "string",
  • "tags": [
    ],
  • "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": [
    ]
}

Update the File with predefined ID

Update the File with predefined ID. Note that file can be uploaded with POST. only.

Request
Security:
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Request Body schema: application/json

File resource.

name
string

Original File name.

extension
string

The File extension.

description
string

The File description.

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.

Responses
200File was updated.
Response Schema: application/json
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.

tags
Array of strings

The tags list.

mime
string

The mime type.

Enum: "image/png" "image/jpeg" "image/gif" "application/pdf" "audio/mpeg"
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>

The upload date/time.

updatedTime
string <date-time>

The latest update date/time.

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.

401Unauthorized access, invalid credentials was used.
403Access forbidden.
404Resource was not found.
422Invalid data was sent.
put/files/{id}
Request samples
application/json
{
  • "name": "string",
  • "extension": "string",
  • "description": "string",
  • "tags": [
    ],
  • "isPublic": true
}
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "name": "string",
  • "extension": "string",
  • "description": "string",
  • "tags": [
    ],
  • "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": [
    ]
}

Delete a File

Delete the File with predefined identifier string.

Request
Security:
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
204File was deleted.
401Unauthorized access, invalid credentials was used.
403Access forbidden.
404Resource was not found.
delete/files/{id}
Request samples
$client->files()->delete('fileId');
Response samples
application/json
{
  • "status": 400,
  • "title": "string",
  • "detail": "string",
  • "error": "string"
}

Download a file

Download a file.

Request
Security:
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

query Parameters
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 {width}x{height}). The image will be returned in the original size if the value is invalid. This parameter will be ignored for non-image files.

Example: imageSize=700x700
header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
200The file was retrieved successfully.
Response Headers
Content-Length
integer

The number of bytes in the file.

Content-Type
string

The MIME type of the file.

Response Schema: application/json
string
302Resource was moved.
401Unauthorized access, invalid credentials was used.
403Access forbidden.
404Resource was not found.
get/files/{id}/download
Request samples
const file = await api.files.download({id: 'my-file-id'});

// access the file ArrayBuffer to view the content 
console.log(file.data);
Response samples
application/json
"string"

Download image in specific format

Download image in specific format. Images are converted server-side.

Request
Security:
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

extension
required
string

File extension which also indicates the desired file format.

Enum: ".png" ".jpg" ".gif"
header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
200The file was retrieved successfully.
Response Headers
Content-Length
integer

The number of bytes in the file.

Content-Type
string

The MIME type of the file.

Response Schema: application/json
string
401Unauthorized access, invalid credentials was used.
403Access forbidden.
404Resource was not found.
422Invalid data was sent.
get/files/{id}/download{extension}
Request samples
curl -i -X GET \
  https://api-sandbox.rebilly.com/files/:id/download:extension \
  -H 'Organization-Id: 4f6cf35x-2c4y-483z-a0a9-158621f77a21' \
  -H 'REB-APIKEY: YOUR_API_KEY_HERE'
Response samples
application/json
"string"