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.

Authorizations:
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
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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
Enum: "customer" "dispute" "gateway-timeline-comment" "invoice" "organization" "payment" "plan" "product" "subscription" "transaction" "customer-timeline-comment" "transaction-timeline-comment" "order-timeline-comment"

Linked object type.

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.

Request samples

$attachments = $client->attachments()->search([
    'filter' => 'relatedType:customer',
]);

Response samples

Content type
application/json
[
  • {
    }
]

Create an Attachment

Create an Attachment.

Authorizations:
header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

Request Body schema: application/json

Attachment resource.

fileId
required
string

Linked File object id.

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

Linked object type.

relatedId
required
string

Linked object Id.

name
string

The Original Attachment name.

description
string

The Attachment description.

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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
Enum: "customer" "dispute" "gateway-timeline-comment" "invoice" "organization" "payment" "plan" "product" "subscription" "transaction" "customer-timeline-comment" "transaction-timeline-comment" "order-timeline-comment"

Linked object type.

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.

Request samples

Content type
application/json
{
  • "fileId": "string",
  • "relatedType": "customer",
  • "relatedId": "string",
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
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.

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

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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
Enum: "customer" "dispute" "gateway-timeline-comment" "invoice" "organization" "payment" "plan" "product" "subscription" "transaction" "customer-timeline-comment" "transaction-timeline-comment" "order-timeline-comment"

Linked object type.

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.

Request samples

$attachment = $client->attachments()->load('attachmentId');

Response samples

Content type
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.

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

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

Request Body schema: application/json

Attachment resource.

fileId
required
string

Linked File object id.

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

Linked object type.

relatedId
required
string

Linked object Id.

name
string

The Original Attachment name.

description
string

The Attachment description.

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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
Enum: "customer" "dispute" "gateway-timeline-comment" "invoice" "organization" "payment" "plan" "product" "subscription" "transaction" "customer-timeline-comment" "transaction-timeline-comment" "order-timeline-comment"

Linked object type.

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.

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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
Enum: "customer" "dispute" "gateway-timeline-comment" "invoice" "organization" "payment" "plan" "product" "subscription" "transaction" "customer-timeline-comment" "transaction-timeline-comment" "order-timeline-comment"

Linked object type.

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.

Request samples

Content type
application/json
{
  • "fileId": "string",
  • "relatedType": "customer",
  • "relatedId": "string",
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
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.

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

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

Responses

Request samples

$client->attachments()->delete('attachmentId');

Response samples

Content type
application/json
{
  • "status": 400,
  • "title": "string",
  • "detail": "string",
  • "error": "string"
}

Retrieve a list of files

Retrieve a list of files.

Authorizations:
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
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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

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>

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.

Request samples

$files = $client->files()->search([
    'filter' => 'name:TestFile',
]);

Response samples

Content type
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.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

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

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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

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>

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.

Request samples

Content type
application/json
Example
{
  • "file": "R0lGODlhAQABAIAAAAUEBAAAACwAAAAAAQABAAACAkQBADs=",
  • "isPublic": false,
  • "name": "logo.png",
  • "description": "My file description",
  • "tags": [
    ]
}

Response samples

Content type
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.

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

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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

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>

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.

Request samples

$file = $client->files()->load('fileId');

Response samples

Content type
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.

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

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

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

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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

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>

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.

Request samples

Content type
application/json
{
  • "name": "string",
  • "extension": "string",
  • "description": "string",
  • "tags": [
    ],
  • "isPublic": true
}

Response samples

Content type
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.

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

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

Responses

Request samples

$client->files()->delete('fileId');

Response samples

Content type
application/json
{
  • "status": 400,
  • "title": "string",
  • "detail": "string",
  • "error": "string"
}

Download a file

Download a file.

Authorizations:
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}$
Example: imageSize=700x700

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.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

Responses

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

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

Content type
application/json
"string"

Download image in specific format

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

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

The resource identifier string.

extension
required
string
Enum: ".png" ".jpg" ".gif"

File extension which also indicates the desired file format.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

Responses

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

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

Content type
application/json
"string"