logo

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:
SecretApiKey or JWT
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
Deprecated

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

It is deprecated. Use servers with /organizations/{organizationId} base path instead.

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
200

A list of Attachments was retrieved successfully.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

get/attachments
Request samples
    4 more
    Python
    Java
    Go
    Ruby
$attachments = $client->attachments()->search([
    'filter' => 'relatedType:customer',
]);
Response samples
application/json
[
  • {
    }
]

Create an Attachment

Create an Attachment.

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

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

It is deprecated. Use servers with /organizations/{organizationId} base path instead.

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" … 3 more
relatedId
required
string

Linked object Id.

name
string

The Original Attachment name.

description
string

The Attachment description.

Responses
201

Attachment was created.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

409

Conflict.

422

Invalid data was sent.

post/attachments
Request samples
    5 more
    C#
    Python
    Java
    Go
    Ruby
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:
SecretApiKey or JWT
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

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

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

It is deprecated. Use servers with /organizations/{organizationId} base path instead.

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
200

Attachment was retrieved successfully.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

404

Resource was not found.

get/attachments/{id}
Request samples
    4 more
    Python
    Java
    Go
    Ruby
$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:
SecretApiKey or JWT
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

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

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

It is deprecated. Use servers with /organizations/{organizationId} base path instead.

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" … 3 more
relatedId
required
string

Linked object Id.

name
string

The Original Attachment name.

description
string

The Attachment description.

Responses
200

Attachment was updated.

201

Attachment was created.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

404

Resource was not found.

409

Conflict.

422

Invalid data was sent.

put/attachments/{id}
Request samples
    5 more
    C#
    Python
    Java
    Go
    Ruby
application/json
{
  • "fileId": "string",
  • "relatedType": "customer",
  • "relatedId": "string",
  • "name": "string",
  • "description": "string"
}
Response samples
    2 more
    409
    422
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:
SecretApiKey or JWT
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

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

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

It is deprecated. Use servers with /organizations/{organizationId} base path instead.

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
204

Attachment was deleted.

401

Unauthorized access, invalid credentials were used.

404

Resource was not found.

delete/attachments/{id}
Request samples
    4 more
    Python
    Java
    Go
    Ruby
$client->attachments()->delete('attachmentId');
Response samples
application/json
{
  • "type": "http://example.com",
  • "status": 400,
  • "title": "string",
  • "detail": "string",
  • "error": "string"
}

Retrieve a list of files

Retrieve a list of files.

Request
Security:
SecretApiKey or JWT
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
Deprecated

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

It is deprecated. Use servers with /organizations/{organizationId} base path instead.

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
200

A list of Files was retrieved successfully.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

get/files
Request samples
    4 more
    Python
    Java
    Go
    Ruby
$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
Security:
SecretApiKey or JWT or PublishableApiKey
header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Deprecated

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

It is deprecated. Use servers with /organizations/{organizationId} base path instead.

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
201

File was created.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

422

Invalid data was sent.

post/files
Request samples
    5 more
    C#
    Python
    Java
    Go
    Ruby
application/json
FileCreateFromInline
FileCreateFromInline
FileCreateFromUrl
{
  • "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:
SecretApiKey or JWT
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

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

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

It is deprecated. Use servers with /organizations/{organizationId} base path instead.

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
200

File was retrieved successfully.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

404

Resource was not found.

get/files/{id}
Request samples
    4 more
    Python
    Java
    Go
    Ruby
$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:
SecretApiKey or JWT
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

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

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

It is deprecated. Use servers with /organizations/{organizationId} base path instead.

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
200

File was updated.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

404

Resource was not found.

422

Invalid data was sent.

put/files/{id}
Request samples
    5 more
    C#
    Python
    Java
    Go
    Ruby
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:
SecretApiKey or JWT
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

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

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

It is deprecated. Use servers with /organizations/{organizationId} base path instead.

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
204

File was deleted.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

404

Resource was not found.

delete/files/{id}
Request samples
    4 more
    Python
    Java
    Go
    Ruby
$client->files()->delete('fileId');
Response samples
application/json
{
  • "type": "http://example.com",
  • "status": 400,
  • "title": "string",
  • "detail": "string",
  • "error": "string"
}

Download a file

Download a file.

Request
Security:
SecretApiKey or JWT
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
Deprecated

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

It is deprecated. Use servers with /organizations/{organizationId} base path instead.

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
200

The file was retrieved successfully.

302

Resource was moved.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

404

Resource was not found.

get/files/{id}/download
Request samples
    3 more
    Java
    Go
    Ruby
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:
SecretApiKey or JWT
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
Deprecated

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

It is deprecated. Use servers with /organizations/{organizationId} base path instead.

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
200

The file was retrieved successfully.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

404

Resource was not found.

422

Invalid data was sent.

get/files/{id}/download{extension}
Request samples
    2 more
    Go
    Ruby
curl -i -X GET \
  https://api-sandbox.rebilly.com/organizations/unknown/files/:id/download:extension \
  -H 'Organization-Id: 4f6cf35x-2c4y-483z-a0a9-158621f77a21' \
  -H 'REB-APIKEY: YOUR_API_KEY_HERE'
Response samples
application/json
"string"
➔ Next to Search