Invitations
/
List invitations to a Brandfolder

Brandfolder OpenAPI Reference (v4)

Welcome to the OpenAPI reference documentation for Brandfolder by Smartsheet!

Download OpenAPI description
openapi.json
openapi.yaml
Languages
Servers
https://brandfolder.com/api/v4/

Assets

Assets are the core resource of Brandfolder. They act like containers that hold all of your digital resources and files, which we call Attachments. They belong to a Section in a Brandfolder and can also exist within many Collections.

Operations

Attachments

Attachments are the representation of digital assets in Brandfolder. Generally speaking, they are actual files but can also be colors, fonts, links to embedded/external media, etc. They belong to an Asset and contain extra metadata related to the files they represent.

Note:

If you need to list all of an organization's attachments, follow these steps:

  1. List all Brandfolders: GET /brandfolders?include=organization
  2. List all sections for each Brandfolder within the target organization: GET /brandfolders/{brandfolder_id}/sections
  3. Iteratively list assets and their attachments for each Section: GET /sections/{section_id}/assets?include=attachments
Operations

Binary upload

Brandfolder's Binary Upload service allows for authenticated users to upload locally stored files into Brandfolder via our API.

Binary Upload is a multi-step process:

  1. Get an upload URL
  2. Upload the file to the storage bucket using one of the methods below :
  3. Create an asset, telling the Brandfolder API the attachment is at that URL.

The Brandfolder Upload Request endpoint will return a response body with a signed upload_url, resumable_upload_url, storage service_type and object_url.

Each Binary Upload request_url and object_url are designed to be used one time for a singular Asset. Both the upload_url and resumable_upload_url will expire 24 hours after they're issued. Assets uploaded to the object_url will be stored for 7 days before being purged. Should any of these URLs expire, you will simply need to restart the workflow to obtain active URLs.

Tip: We recommend that you use the Resumable Upload flow if you have poor internet connection, you're uploading local files that are larger than 200MB or if you're uploading files from a server that are larger than 500MB.

Upload Request Flow

Operations

Brandfolders

Brandfolders are nested directly underneath an Organization in the overall heirarchy. They can have many Collections, Sections, and Assets.

Operations

Collections

Collections are nested under a Brandfolder and contain many Assets. They are mainly used as an additional way to organize, manage, share, and restrict access to a subset of Assets within your Brandfolder without having to upload Assets to multiple places.

Operations

Custom fields

Custom Fields can be assigned to Assets and are generally helpful for organizing and searching Assets within a Brandfolder, as well as for understanding more details about each Asset.

Each Custom Field is essentially a key/value pair associated with exactly one Asset. Keys and values are always a string type, so use "123" instead of 123.

For example, if you have several Assets that represent products you sell in different colors, you might create a Custom Field for each of those Assets with a key of "color" and a value of "blue" or "red", etc. If you modify or delete a "color":"blue" Custom Field for any particular Asset, it will not affect other Custom Fields on other Assets, even if they have the same key and/or value.

IMPORTANT: Think carefully about whether Tags or Custom Fields are better suited to meet the needs of your particular use case.

Operations

Invitations

Invitations are exactly what they sound like and can be created to invite Users to join your Organization, Brandfolder, or Collection as a guest, collaborator, admin, or (when inviting someone to an Organization) owner.

Learn more about the permission levels you can grant Users in our Knowledge Base article on User Permissions.

Operations

List invitations to a Brandfolder

Request

Lists invitations to the matching Brandfolder.

Path
brandfolder_idstringrequired

Unique identifier for the resource instance.

Example: oqgiju-21olts-ce9egi
Query
fieldsstring

Set it to created_at to return it as part of the invitation's attributes in the response.

Allowed value: created_at

WARNING: This parameter can slow response times.

Example: fields=created_at
includestring

Set it to a comma-separated list (no spaces) of any of the following record names to return those records related to the invitations you're fetching. Related records are returned in an included array in the response.

Allowed values:

  • inviter
  • inviteable

WARNING: This parameter can slow response times.

Example: include=inviter
Headers
Content-Typestringrequired
Value"application/json"
Example: application/json
Acceptstringrequired
Value"application/json"
Example: application/json
Authorizationstringrequired

Bearer token for authentication.

Example: Bearer BF_API_KEY
curl -i -X GET \
  'https://brandfolder.com/api/v4/brandfolders/oqgiju-21olts-ce9egi/invitations?fields=created_at&include=inviter' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json'

Responses

Invitations to the matching Brandfolder.

Bodyapplication/json
dataArray of objects(Invitation)required
data[].​idstringrequired

Unique identifier for the resource instance.

Example: "a3dlao-hd6so4-7d91d2"
data[].​typestringrequired

The type of the resource.

Value"invitations"
data[].​attributesobject(Invitation attributes)required
data[].​attributes.​emailstringrequired

Email address of the recipient.

Example: "test@example.com"
data[].​attributes.​permission_levelstring

Access to grant the recipient.

Example: "guest"
data[].​attributes.​personal_messagestring

A message for the recipient.

Example: "Welcome to my Brandfolder!"
data[].​attributes.​invitation_urlstring

The invitation's URL.

Example: "https://brandfolder.com/invitations/abc123"
metaobject(Pagination metadata)required

Page context information.

meta.​current_pageinteger(int32)>= 1required
Default 1
Example: 1
meta.​next_pageobject or nullrequired
Default null
Example: null
meta.​prev_pageobject or nullrequired
Default null
Example: null
meta.​total_pagesnumber>= 1required
Default 1
Example: 1
meta.​total_countnumber>= 0required
Default 0
Example: 1
Response
application/json
{
  "data": [
    { … }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

Create an invitation to a Brandfolder

Request

Creates an invitation to the matching Brandfolder.

Path
brandfolder_idstringrequired

Unique identifier for the resource instance.

Example: oqgiju-21olts-ce9egi
Headers
Content-Typestringrequired
Value"application/json"
Example: application/json
Acceptstringrequired
Value"application/json"
Example: application/json
Authorizationstringrequired

Bearer token for authentication.

Example: Bearer BF_API_KEY
Bodyapplication/json

An invitation to the Brandfolder.

dataobjectrequired
data.​attributesobjectrequired
data.​attributes.​emailstringrequired

Email address of invitee.

Example: "test@example.com"
data.​attributes.​permission_levelstringrequired

Access to grant invitee.

Note: owner is only valid when inviting someone to an Organization.

Learn more about the permission levels you can grant Users in our Knowledge Base article on User Permissions.

Enum"guest""collaborator""admin""owner"
Example: "guest"
data.​attributes.​personal_messagestring

A message for invitee.

Example: "Welcome to my Brandfolder!"
data.​attributes.​prevent_emailboolean

Set this to true to skip sending an invitation email to the invitee.

Default false
curl -i -X POST \
  https://brandfolder.com/api/v4/brandfolders/oqgiju-21olts-ce9egi/invitations \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "attributes": {
        "email": "test@example.com",
        "permission_level": "guest",
        "personal_message": "Welcome to my Brandfolder!",
        "prevent_email": false
      }
    }
  }'

Responses

The new invitation.

Bodyapplication/json
dataobjectrequired
data.​attributesobject(Invitation)
metaobjectrequired
meta.​auto_acceptedboolean
Example: false
Response
application/json
{
  "data": {
    "attributes": { … }
  },
  "meta": {
    "auto_accepted": false
  }
}

List invitations to an organization

Request

Lists invitations to the matching organization.

Path
organization_idstringrequired

Unique identifier for the resource instance.

Example: oqgkkd-fr5iv4-cocc75
Query
fieldsstring

Set it to created_at to return it as part of the invitation's attributes in the response.

Allowed value: created_at

WARNING: This parameter can slow response times.

Example: fields=created_at
includestring

Set it to a comma-separated list (no spaces) of any of the following record names to return those records related to the invitations you're fetching. Related records are returned in an included array in the response.

Allowed values:

  • inviter
  • inviteable

WARNING: This parameter can slow response times.

Example: include=inviter
Headers
Content-Typestringrequired
Value"application/json"
Example: application/json
Acceptstringrequired
Value"application/json"
Example: application/json
Authorizationstringrequired

Bearer token for authentication.

Example: Bearer BF_API_KEY
curl -i -X GET \
  'https://brandfolder.com/api/v4/organizations/oqgkkd-fr5iv4-cocc75/invitations?fields=created_at&include=inviter' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json'

Responses

Invitations to the matching organization.

Bodyapplication/json
dataArray of objects(Invitation)required
data[].​idstringrequired

Unique identifier for the resource instance.

Example: "a3dlao-hd6so4-7d91d2"
data[].​typestringrequired

The type of the resource.

Value"invitations"
data[].​attributesobject(Invitation attributes)required
data[].​attributes.​emailstringrequired

Email address of the recipient.

Example: "test@example.com"
data[].​attributes.​permission_levelstring

Access to grant the recipient.

Example: "guest"
data[].​attributes.​personal_messagestring

A message for the recipient.

Example: "Welcome to my Brandfolder!"
data[].​attributes.​invitation_urlstring

The invitation's URL.

Example: "https://brandfolder.com/invitations/abc123"
metaobject(Pagination metadata)required

Page context information.

meta.​current_pageinteger(int32)>= 1required
Default 1
Example: 1
meta.​next_pageobject or nullrequired
Default null
Example: null
meta.​prev_pageobject or nullrequired
Default null
Example: null
meta.​total_pagesnumber>= 1required
Default 1
Example: 1
meta.​total_countnumber>= 0required
Default 0
Example: 1
Response
application/json
{
  "data": [
    { … }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

Create an invitation to an organization

Request

Creates an invitation to the matching organization.

Path
organization_idstringrequired

Unique identifier for the resource instance.

Example: oqgkkd-fr5iv4-cocc75
Headers
Content-Typestringrequired
Value"application/json"
Example: application/json
Acceptstringrequired
Value"application/json"
Example: application/json
Authorizationstringrequired

Bearer token for authentication.

Example: Bearer BF_API_KEY
Bodyapplication/json

An invitation to the organization.

dataobjectrequired
data.​attributesobjectrequired
data.​attributes.​emailstringrequired

Email address of invitee.

Example: "test@example.com"
data.​attributes.​permission_levelstringrequired

Access to grant invitee.

Note: owner is only valid when inviting someone to an Organization.

Learn more about the permission levels you can grant Users in our Knowledge Base article on User Permissions.

Enum"guest""collaborator""admin""owner"
Example: "guest"
data.​attributes.​personal_messagestring

A message for invitee.

Example: "Welcome to my Brandfolder!"
data.​attributes.​prevent_emailboolean

Set this to true to skip sending an invitation email to the invitee.

Default false
curl -i -X POST \
  https://brandfolder.com/api/v4/organizations/oqgkkd-fr5iv4-cocc75/invitations \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "attributes": {
        "email": "test@example.com",
        "permission_level": "guest",
        "personal_message": "Welcome to my Brandfolder!",
        "prevent_email": false
      }
    }
  }'

Responses

The new invitation.

Bodyapplication/json
dataobjectrequired
data.​attributesobject(Invitation)
metaobjectrequired
meta.​auto_acceptedboolean
Example: false
Response
application/json
{
  "data": {
    "attributes": { … }
  },
  "meta": {
    "auto_accepted": false
  }
}

List invitations to a collection

Request

Lists invitations to the matching collection.

Path
collection_idstringrequired

Unique identifier for the resource instance.

Example: oqgiju-21olts-ce9egi
Query
fieldsstring

Set it to created_at to return it as part of the invitation's attributes in the response.

Allowed value: created_at

WARNING: This parameter can slow response times.

Example: fields=created_at
includestring

Set it to a comma-separated list (no spaces) of any of the following record names to return those records related to the invitations you're fetching. Related records are returned in an included array in the response.

Allowed values:

  • inviter
  • inviteable

WARNING: This parameter can slow response times.

Example: include=inviter
Headers
Content-Typestringrequired
Value"application/json"
Example: application/json
Authorizationstringrequired

Bearer token for authentication.

Example: Bearer BF_API_KEY
curl -i -X GET \
  'https://brandfolder.com/api/v4/collections/oqgiju-21olts-ce9egi/invitations?fields=created_at&include=inviter' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json'

Responses

Invitations to the matching collection.

Bodyapplication/json
dataArray of objects(Invitation)required
data[].​idstringrequired

Unique identifier for the resource instance.

Example: "a3dlao-hd6so4-7d91d2"
data[].​typestringrequired

The type of the resource.

Value"invitations"
data[].​attributesobject(Invitation attributes)required
data[].​attributes.​emailstringrequired

Email address of the recipient.

Example: "test@example.com"
data[].​attributes.​permission_levelstring

Access to grant the recipient.

Example: "guest"
data[].​attributes.​personal_messagestring

A message for the recipient.

Example: "Welcome to my Brandfolder!"
data[].​attributes.​invitation_urlstring

The invitation's URL.

Example: "https://brandfolder.com/invitations/abc123"
metaobject(Pagination metadata)required

Page context information.

meta.​current_pageinteger(int32)>= 1required
Default 1
Example: 1
meta.​next_pageobject or nullrequired
Default null
Example: null
meta.​prev_pageobject or nullrequired
Default null
Example: null
meta.​total_pagesnumber>= 1required
Default 1
Example: 1
meta.​total_countnumber>= 0required
Default 0
Example: 1
Response
application/json
{
  "data": [
    { … }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

Create an invitation to a collection

Request

Creates an invitation to the matching collection.

Path
collection_idstringrequired

Unique identifier for the resource instance.

Example: oqgiju-21olts-ce9egi
Headers
Content-Typestringrequired
Value"application/json"
Example: application/json
Authorizationstringrequired

Bearer token for authentication.

Example: Bearer BF_API_KEY
Bodyapplication/json

An invitation to the collection.

dataobjectrequired
data.​attributesobjectrequired
data.​attributes.​emailstringrequired

Email address of invitee.

Example: "test@example.com"
data.​attributes.​permission_levelstringrequired

Access to grant invitee.

Note: owner is only valid when inviting someone to an Organization.

Learn more about the permission levels you can grant Users in our Knowledge Base article on User Permissions.

Enum"guest""collaborator""admin""owner"
Example: "guest"
data.​attributes.​personal_messagestring

A message for invitee.

Example: "Welcome to my Brandfolder!"
data.​attributes.​prevent_emailboolean

Set this to true to skip sending an invitation email to the invitee.

Default false
curl -i -X POST \
  https://brandfolder.com/api/v4/collections/oqgiju-21olts-ce9egi/invitations \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "attributes": {
        "email": "test@example.com",
        "permission_level": "guest",
        "personal_message": "Welcome to my Brandfolder!",
        "prevent_email": false
      }
    }
  }'

Responses

The new invitation.

Bodyapplication/json
dataobjectrequired
data.​attributesobject(Invitation)
metaobjectrequired
meta.​auto_acceptedboolean
Example: false
Response
application/json
{
  "data": {
    "attributes": { … }
  },
  "meta": {
    "auto_accepted": false
  }
}

List invitations to a portal

Request

Lists invitations to the matching portal.

Important: You can get the portal ID in the response from Fetch an organization.

Path
portal_idstringrequired

Unique identifier for the resource instance.

Example: oqgiju-21olts-ce9egi
Query
fieldsstring

Set it to created_at to return it as part of the invitation's attributes in the response.

Allowed value: created_at

WARNING: This parameter can slow response times.

Example: fields=created_at
includestring

Set it to a comma-separated list (no spaces) of any of the following record names to return those records related to the invitations you're fetching. Related records are returned in an included array in the response.

Allowed values:

  • inviter
  • inviteable

WARNING: This parameter can slow response times.

Example: include=inviter
Headers
Content-Typestringrequired
Value"application/json"
Example: application/json
Authorizationstringrequired

Bearer token for authentication.

Example: Bearer BF_API_KEY
curl -i -X GET \
  'https://brandfolder.com/api/v4/portals/oqgiju-21olts-ce9egi/invitations?fields=created_at&include=inviter' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json'

Responses

Invitations to the matching portal.

Bodyapplication/json
dataArray of objects(Invitation)required
data[].​idstringrequired

Unique identifier for the resource instance.

Example: "a3dlao-hd6so4-7d91d2"
data[].​typestringrequired

The type of the resource.

Value"invitations"
data[].​attributesobject(Invitation attributes)required
data[].​attributes.​emailstringrequired

Email address of the recipient.

Example: "test@example.com"
data[].​attributes.​permission_levelstring

Access to grant the recipient.

Example: "guest"
data[].​attributes.​personal_messagestring

A message for the recipient.

Example: "Welcome to my Brandfolder!"
data[].​attributes.​invitation_urlstring

The invitation's URL.

Example: "https://brandfolder.com/invitations/abc123"
metaobject(Pagination metadata)required

Page context information.

meta.​current_pageinteger(int32)>= 1required
Default 1
Example: 1
meta.​next_pageobject or nullrequired
Default null
Example: null
meta.​prev_pageobject or nullrequired
Default null
Example: null
meta.​total_pagesnumber>= 1required
Default 1
Example: 1
meta.​total_countnumber>= 0required
Default 0
Example: 1
Response
application/json
{
  "data": [
    { … }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

Create an invitation to a portal

Request

Creates an invitation to the matching portal.

Path
portal_idstringrequired

Unique identifier for the resource instance.

Example: oqgiju-21olts-ce9egi
Headers
Content-Typestringrequired
Value"application/json"
Example: application/json
Authorizationstringrequired

Bearer token for authentication.

Example: Bearer BF_API_KEY
Bodyapplication/json

An invitation to the portal.

dataobjectrequired
data.​attributesobjectrequired
data.​attributes.​emailstringrequired

Email address of invitee.

Example: "test@example.com"
data.​attributes.​permission_levelstringrequired

Access to grant invitee.

Note: owner is only valid when inviting someone to an Organization.

Learn more about the permission levels you can grant Users in our Knowledge Base article on User Permissions.

Enum"guest""collaborator""admin""owner"
Example: "guest"
data.​attributes.​personal_messagestring

A message for invitee.

Example: "Welcome to my Brandfolder!"
data.​attributes.​prevent_emailboolean

Set this to true to skip sending an invitation email to the invitee.

Default false
curl -i -X POST \
  https://brandfolder.com/api/v4/portals/oqgiju-21olts-ce9egi/invitations \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "attributes": {
        "email": "test@example.com",
        "permission_level": "guest",
        "personal_message": "Welcome to my Brandfolder!",
        "prevent_email": false
      }
    }
  }'

Responses

The new invitation.

Bodyapplication/json
dataobjectrequired
data.​attributesobject(Invitation)
metaobjectrequired
meta.​auto_acceptedboolean
Example: false
Response
application/json
{
  "data": {
    "attributes": { … }
  },
  "meta": {
    "auto_accepted": false
  }
}

List invitations to a Brandguide

Request

Lists invitations to the matching Brandguide.

Important: You can get the Brandguide ID in the response from Fetch an organization.

Path
brandguide_idstringrequired

Unique identifier for the resource instance.

Example: oqgiju-21olts-ce9egi
Query
fieldsstring

Set it to created_at to return it as part of the invitation's attributes in the response.

Allowed value: created_at

WARNING: This parameter can slow response times.

Example: fields=created_at
includestring

Set it to a comma-separated list (no spaces) of any of the following record names to return those records related to the invitations you're fetching. Related records are returned in an included array in the response.

Allowed values:

  • inviter
  • inviteable

WARNING: This parameter can slow response times.

Example: include=inviter
Headers
Content-Typestringrequired
Value"application/json"
Example: application/json
Authorizationstringrequired

Bearer token for authentication.

Example: Bearer BF_API_KEY
curl -i -X GET \
  'https://brandfolder.com/api/v4/brandguides/oqgiju-21olts-ce9egi/invitations?fields=created_at&include=inviter' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json'

Responses

Invitations to the matching Brandguide.

Bodyapplication/json
dataArray of objects(Invitation)required
data[].​idstringrequired

Unique identifier for the resource instance.

Example: "a3dlao-hd6so4-7d91d2"
data[].​typestringrequired

The type of the resource.

Value"invitations"
data[].​attributesobject(Invitation attributes)required
data[].​attributes.​emailstringrequired

Email address of the recipient.

Example: "test@example.com"
data[].​attributes.​permission_levelstring

Access to grant the recipient.

Example: "guest"
data[].​attributes.​personal_messagestring

A message for the recipient.

Example: "Welcome to my Brandfolder!"
data[].​attributes.​invitation_urlstring

The invitation's URL.

Example: "https://brandfolder.com/invitations/abc123"
metaobject(Pagination metadata)required

Page context information.

meta.​current_pageinteger(int32)>= 1required
Default 1
Example: 1
meta.​next_pageobject or nullrequired
Default null
Example: null
meta.​prev_pageobject or nullrequired
Default null
Example: null
meta.​total_pagesnumber>= 1required
Default 1
Example: 1
meta.​total_countnumber>= 0required
Default 0
Example: 1
Response
application/json
{
  "data": [
    { … }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

Create an invitation to a Brandguide

Request

Creates an invitation to the matching Brandguide.

Path
brandguide_idstringrequired

Unique identifier for the resource instance.

Example: oqgiju-21olts-ce9egi
Headers
Content-Typestringrequired
Value"application/json"
Example: application/json
Authorizationstringrequired

Bearer token for authentication.

Example: Bearer BF_API_KEY
Bodyapplication/json

An invitation to the Brandguide.

dataobjectrequired
data.​attributesobjectrequired
data.​attributes.​emailstringrequired

Email address of invitee.

Example: "test@example.com"
data.​attributes.​permission_levelstringrequired

Access to grant invitee.

Note: owner is only valid when inviting someone to an Organization.

Learn more about the permission levels you can grant Users in our Knowledge Base article on User Permissions.

Enum"guest""collaborator""admin""owner"
Example: "guest"
data.​attributes.​personal_messagestring

A message for invitee.

Example: "Welcome to my Brandfolder!"
data.​attributes.​prevent_emailboolean

Set this to true to skip sending an invitation email to the invitee.

Default false
curl -i -X POST \
  https://brandfolder.com/api/v4/brandguides/oqgiju-21olts-ce9egi/invitations \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "attributes": {
        "email": "test@example.com",
        "permission_level": "guest",
        "personal_message": "Welcome to my Brandfolder!",
        "prevent_email": false
      }
    }
  }'

Responses

The new invitation.

Bodyapplication/json
dataobjectrequired
data.​attributesobject(Invitation)
metaobjectrequired
meta.​auto_acceptedboolean
Example: false
Response
application/json
{
  "data": {
    "attributes": { … }
  },
  "meta": {
    "auto_accepted": false
  }
}

Fetch an invitation

Request

Gets a matching invitation.

Path
invitation_idstringrequired

Unique identifier for the resource instance.

Example: a3dlao-hd6so4-7d91d2
Query
fieldsstring

Set it to created_at to return it as part of the invitation's attributes in the response.

Allowed value: created_at

WARNING: This parameter can slow response times.

Example: fields=created_at
includestring

Set it to inviteable to include the Brandfolder, Collection, or Organization that this Invitation is for.

Allowed value: inviteable

WARNING: This parameter can slow response times.

Example: include=inviteable
Headers
Content-Typestringrequired
Value"application/json"
Example: application/json
Authorizationstringrequired

Bearer token for authentication.

Example: Bearer BF_API_KEY
Acceptstringrequired
Value"application/json"
Example: application/json
curl -i -X GET \
  'https://brandfolder.com/api/v4/invitations/a3dlao-hd6so4-7d91d2?fields=created_at&include=inviteable' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json'

Responses

The matching invitation.

Bodyapplication/json
dataobject(Invitation)required
data.​idstringrequired

Unique identifier for the resource instance.

Example: "a3dlao-hd6so4-7d91d2"
data.​typestringrequired

The type of the resource.

Value"invitations"
data.​attributesobject(Invitation attributes)required
data.​attributes.​emailstringrequired

Email address of the recipient.

Example: "test@example.com"
data.​attributes.​permission_levelstring

Access to grant the recipient.

Example: "guest"
data.​attributes.​personal_messagestring

A message for the recipient.

Example: "Welcome to my Brandfolder!"
data.​attributes.​invitation_urlstring

The invitation's URL.

Example: "https://brandfolder.com/invitations/abc123"
Response
application/json
{
  "data": {
    "id": "a3dlao-hd6so4-7d91d2",
    "type": "invitations",
    "attributes": { … }
  }
}

Delete an invitation

Request

Deletes the matching invitation.

Path
invitation_idstringrequired

Unique identifier for the resource instance.

Example: a3dlao-hd6so4-7d91d2
Headers
Content-Typestringrequired
Value"application/json"
Example: application/json
Authorizationstringrequired

Bearer token for authentication.

Example: Bearer BF_API_KEY
curl -i -X DELETE \
  https://brandfolder.com/api/v4/invitations/a3dlao-hd6so4-7d91d2 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json'

Responses

Successful response (always an empty object)

Bodyapplication/json
object
Response
application/json
{}

Labels

Brandfolder's Labels are an enhanced organization and findability feature meant to provide the peace of mind that comes with an organization's existing folder structure. Think of Labels like your music playlists--any asset can be assigned to a label or multiple labels.

Labels are not turned on for every account. If you are unsure whether you have or need Labels, please contact brandfoldersupport@smartsheet.com.

Operations

Organizations

An Organization is the top level resource of all objects in Brandfolder. It can have many Brandfolders nested beneath it.

Operations

Sections

Sections are nested under a Brandfolder and contain many Assets. They exist to help keep Assets organized within a Brandfolder. They also determine which type of digital assets can be uploaded within them (files, external media, fonts, etc.).

Operations

Tags

Tags can be assigned to Assets and are generally helpful for organizing and searching Assets within a Brandfolder.

Each Tag is essentially a keyword associated with exactly one Asset.

For example, if you have several Assets that represent products you sell, you might create a "product" Tag for each one. If you modify or delete the "product" Tag for any particular Asset, it will not affect other Tags with the same value on other Assets.

Tags have a read-only attribute called auto_generated which indicates if the Tag was created automatically by our smart analysis of the file Attachment(s) (true) or if a User created the Tag (false).

IMPORTANT: Think carefully about whether Tags or Custom Fields are better suited to meet the needs of your particular use case.

Operations

User permissions

User permissions describe relationships between Organizations, Brandfolders, Collections, Portals or Brandguides and the users that have access to them.

Learn more about permissioning in our Knowledge Base article on User Permissions.

Operations

Webhooks

The Brandfolder Webhooks service allows you to subscribe to event-based notifications (callbacks) when a qualifying event is triggered within Brandfolder. Asset data will then be sent to the user-provided callback_url at the time the subscribed event occurs within the specified Brandfolder.

NOTE: The callback_url must be accessible from the public internet, meaning any localhost, private network domains, or domains that require authentication will all fail.

Authentication

Utilizing Webhooks requires authentication with the resource (Brandfolder) being subscribed to. A user's unique API Key is required in a header for actions on all endpoints related to the Webhooks service.

There are two required headers in each request:

Content-Type: application/json
Authorization: Bearer <api_key>

The provided API Key is checked against any provided resource (where applicable) to confirm the appropriate permissions.

Service Details

The Brandfolder Webhooks service allows for subscriptions to events within individual Brandfolders.

NOTE: Asset data updates made at the Collection level will trigger a Brandfolder Webhook subscription. Since assets live at the Brandfolder level, any updates made at the Collection level would be reflected on the Brandfolder level as well, thus triggering a Webhook.

Due to the way Brandfolder manages assets, you will see both an "asset.create" event and an "asset.update" event upon creation of a new asset. A create event is triggered when Brandfolder recognizes the new asset and begins to process it for use. An update event is triggered when the asset is ready for use.

The following event types trigger webhooks:

  • asset.create - Asset creation. A new asset has been added to a subscribed Brandfolder.
  • asset.update - Asset update. Asset data has been updated within a subscribed Brandfolder. One or more of the following asset attributes has been updated:
    • Name
    • Description
    • Section
    • Approval status
    • Expiration status
    • Comments & Annotations
      • Adding / Updating
      • Deleting
    • Tags
      • Adding / Updating
      • Deleting
    • Custom Fields
      • Adding / Updating
      • Deleting
  • asset.delete - Asset deletion. An asset has been removed from within a subscribed Brandfolder.

Once a Webhook subscription as been created, the payload that will be sent to the user-provided callback_url after an event has been triggered will have the following structure:

{
    "data": {
        "attributes": {
            "key": "<unique_asset_identifier>",
            "event_time": "<event occurance timestamp in format YYYY-MM-DD HH:MM:SS.000000 with six decimal place microsecond precision>",
            "event_type": "<the event type that triggered the webhook>",
            "brandfolder_key": "<unique_brandfolder_identifier>",
            "organization_key": "<unique_organization_identifier>"
        },
        "webhook_id": "<webhook_id>"
    }
}

NOTE: The callback payload is a "skinny" payload -- it indicates which assets changed and the type of event that occurred, but does not contain any data from the assets themselves.

The Brandfolder Webhook service requires your application to immediately acknowledge receipt of any Webhooks by returning a 2xx HTTP status code. If Brandfolder does not receive an acknowledgement or any non 2xx HTTP status code is returned, Brandfolder will retry the Webhook up to 15 times with exponentially increasing wait times in between.

Any Webhook subscriptions that continue to fail without remedy will be made inactive.

Messages may be sent out of order to the callback_url associated with a Webhook subscription. The event_time provided in the payload can be used to order events.

If the API Key associated with a Webhook subscription loses access to the associated resource, the subscription will be deactivated within 30 minutes.

Operations

Schemas