Team API (1.0)

Download OpenAPI specification:Download

The team API lets you manage users, departments, locations, and cards.

Users

Endpoints for user management.

List users

This endpoint lists all users. To find a user id by email, you can filter using the email query parameter.

SecurityOAuth2
Request
query Parameters
cursor
string or null
limit
integer or null <int32>
email
string or null

Currently only support filtering by a single email or a single remote_display_id.

remote_display_id
string or null

Currently only support filtering by a single email or a single remote_display_id.

expand[]
Array of strings or null

Expandable fields that can be included in the response by passing in a query parameter e.g. ?expand[]=limit

Responses
200

listUsers 200 response

get/v2/users
Request samples
Response samples
application/json
{
  • "next_cursor": "string",
  • "items": [
    ]
}

Invite user

This endpoint invites a new user as an employee. To update user's role, check out this article.

SecurityOAuth2
Request
header Parameters
Idempotency-Key
string or null
Request Body schema: application/json
first_name
required
string non-empty
last_name
required
string non-empty
email
required
string <email>
manager_id
string or null
department_id
string or null
location_id
string or null
title_id
string or null
object or null

The metadata or customized attributes of the user. Maximum number of entries: 100

Responses
200

createUser 200 response

post/v2/users
Request samples
application/json
{
  • "first_name": "string",
  • "last_name": "string",
  • "email": "user@example.com",
  • "manager_id": "string",
  • "department_id": "string",
  • "location_id": "string",
  • "title_id": "string",
  • "metadata": {
    }
}
Response samples
application/json
{
  • "id": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "string",
  • "status": "INVITED",
  • "manager_id": "string",
  • "department_id": "string",
  • "location_id": "string",
  • "title_id": "string",
  • "metadata": {
    },
  • "remote_display_id": "string"
}

Get current user

This endpoint returns the user associated with the OAuth2 access token.

SecurityOAuth2
Responses
200

getMe 200 response

get/v2/users/me
Request samples
Response samples
application/json
{
  • "id": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "string",
  • "status": "INVITED",
  • "manager_id": "string",
  • "department_id": "string",
  • "location_id": "string",
  • "title_id": "string",
  • "metadata": {
    },
  • "remote_display_id": "string"
}

Get user

This endpoint gets a user by ID.

SecurityOAuth2
Request
path Parameters
id
required
string
Responses
200

getUserById 200 response

get/v2/users/{id}
Request samples
Response samples
application/json
{
  • "id": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "string",
  • "status": "INVITED",
  • "manager_id": "string",
  • "department_id": "string",
  • "location_id": "string",
  • "title_id": "string",
  • "metadata": {
    },
  • "remote_display_id": "string"
}

Update user

This endpoint updates a user. Any parameters not provided will be left unchanged.

SecurityOAuth2
Request
path Parameters
id
required
string
header Parameters
Idempotency-Key
string or null
Request Body schema: application/json
status
string or null

Acceptable user status for update. To suspend a user, set status to 'disabled'. To unsuspend a user, set status to 'active'.

Enum: "ACTIVE" "DISABLED"
manager_id
string or null

The user id of the manager of this user

department_id
string or null
location_id
string or null
title_id
string or null
object or null

The metadata or customized attributes of the user. Maximum number of entries: 100

Responses
200

updateUser 200 response

put/v2/users/{id}
Request samples
application/json
{
  • "status": "ACTIVE",
  • "manager_id": "string",
  • "department_id": "string",
  • "location_id": "string",
  • "title_id": "string",
  • "metadata": {
    }
}
Response samples
application/json
{
  • "id": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "string",
  • "status": "INVITED",
  • "manager_id": "string",
  • "department_id": "string",
  • "location_id": "string",
  • "title_id": "string",
  • "metadata": {
    },
  • "remote_display_id": "string"
}

Get limit for the user

This endpoint gets the monthly limit for the user including the monthly available limit.

SecurityOAuth2
Request
path Parameters
id
required
string
Responses
200

getUserLimit 200 response

get/v2/users/{id}/limit
Request samples
Response samples
application/json
{
  • "monthly_limit": {
    },
  • "monthly_available": {
    }
}

Set limit for the user

This endpoint sets the monthly limit for a user. The limit amount must be non-negative. To unset the monthly limit of the user, just set monthly_limit to null.

SecurityOAuth2
Request
path Parameters
id
required
string
header Parameters
Idempotency-Key
string or null
Request Body schema: application/json
object or null

Money fields can be signed or unsigned. Fields are signed (an unsigned value will be interpreted as positive). The amount of money will be represented in the smallest denomination of the currency indicated. For example, USD 7.00 will be represented in cents with an amount of 700.

Responses
200

setUserLimit 200 response

post/v2/users/{id}/limit
Request samples
application/json
{
  • "monthly_limit": {
    }
}
Response samples
application/json
{
  • "monthly_limit": {
    },
  • "monthly_available": {
    }
}

Locations

Endpoints for location management.

List locations

This endpoint lists all locations.

SecurityOAuth2
Request
query Parameters
cursor
string or null
limit
integer or null <int32>
name
string or null
Responses
200

listLocations 200 response

get/v2/locations
Request samples
Response samples
application/json
{
  • "next_cursor": "string",
  • "items": [
    ]
}

Create location

This endpoint creates a new location.

SecurityOAuth2
Request
header Parameters
Idempotency-Key
string or null
Request Body schema: application/json
name
required
string non-empty

Name of the location

description
string or null

Description of the location

Responses
200

createLocation 200 response

post/v2/locations
Request samples
application/json
{
  • "name": "string",
  • "description": "string"
}
Response samples
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string"
}

Get location

This endpoint gets a location by ID.

SecurityOAuth2
Request
path Parameters
id
required
string
Responses
200

getLocationById 200 response

get/v2/locations/{id}
Request samples
Response samples
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string"
}

Departments

Endpoints for department management.

List departments

This endpoint lists all departments.

SecurityOAuth2
Request
query Parameters
cursor
string or null
limit
integer or null <int32>
name
string or null
Responses
200

listDepartments 200 response

get/v2/departments
Request samples
Response samples
application/json
{
  • "next_cursor": "string",
  • "items": [
    ]
}

Create department

This endpoint creates a new department

SecurityOAuth2
Request
header Parameters
Idempotency-Key
string or null
Request Body schema: application/json
name
required
string non-empty

Name of the department

description
string or null

Description of the department

Responses
200

createDepartment 200 response

post/v2/departments
Request samples
application/json
{
  • "name": "string",
  • "description": "string"
}
Response samples
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string"
}

Get department

This endpoint gets a department by ID.

SecurityOAuth2
Request
path Parameters
id
required
string
Responses
200

getDepartmentById 200 response

get/v2/departments/{id}
Request samples
Response samples
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string"
}

Titles

Endpoints for title management.

List titles

This endpoint lists all titles.

SecurityOAuth2
Request
query Parameters
cursor
string or null
limit
integer or null <int32>
name
string or null
Responses
200

listTitles 200 response

get/v2/titles
Request samples
Response samples
application/json
{
  • "next_cursor": "string",
  • "items": [
    ]
}

Create title

This endpoint creates a new title

SecurityOAuth2
Request
header Parameters
Idempotency-Key
string or null
Request Body schema: application/json
name
required
string non-empty

Name of the title

Responses
200

createTitle 200 response

post/v2/titles
Request samples
application/json
{
  • "name": "string"
}
Response samples
application/json
{
  • "id": "string",
  • "name": "string"
}

Get title

This endpoint gets a title by ID.

SecurityOAuth2
Request
path Parameters
id
required
string
Responses
200

getTitleById 200 response

get/v2/titles/{id}
Request samples
Response samples
application/json
{
  • "id": "string",
  • "name": "string"
}

Cards

Endpoints for card management.

List cards

Lists all cards by a user_id. Only cards with limit_type = CARD have spend_controls

SecurityOAuth2
Request
query Parameters
user_id
string or null
cursor
string or null
limit
integer or null <int32>
Responses
200

listCardsByUserId 200 response

get/v2/cards
Request samples
Response samples
application/json
{
  • "next_cursor": "string",
  • "items": [
    ]
}

Create card

Creates a new card. The spend_controls field is required when limit_type = CARD. The mailing_address field is required for physical cards and is the shipping address used to send the card; it is not the same as the billing and mailing address used for online purchases. The first 2 lines of this address must be under 60 characters long. Each user can only have up to 10 active physical cards. For Empower accounts, this endpoint requires budget management. If your account does not have access to budget management features, a 403 response status will be returned. If this is the case and you want to gain access to this endpoint, please contact Brex support.

SecurityOAuth2
Request
header Parameters
Idempotency-Key
required
string
Request Body schema: application/json
required
object (CardOwner)
card_name
required
string non-empty
card_type
required
string (CardType)
Enum: "VIRTUAL" "PHYSICAL"
limit_type
required
string (LimitType)

limit_type = CARD for vendor cards. Vendor cards must have a card_type of VIRTUAL and do not rely on the user specific limit.

For corporate cards, limit_type = USER.

Learn more about different card types here.

Enum: "CARD" "USER"
object or null

When limit_type = CARD, spend_controls must be set. When limit type = USER, spend_controls must be null.

object or null

Company business address (must be in the US; no PO box or virtual/forwarding addresses allowed).

object or null

Set of key value pairs associated with this object. Please do not store any personally identifiable or sensitive information here. Limitations: maximum of 50 keys, keys cannot exceed 40 characters, values cannot exceed 500 characters.

object or null
Responses
200

createCard 200 response

post/v2/cards
Request samples
application/json
{
  • "owner": {
    },
  • "card_name": "string",
  • "card_type": "VIRTUAL",
  • "limit_type": "CARD",
  • "spend_controls": {
    },
  • "mailing_address": {
    },
  • "metadata": {
    },
  • "card_attribute_preferences": {
    }
}
Response samples
application/json
{
  • "id": "string",
  • "owner": {
    },
  • "status": "ACTIVE",
  • "last_four": "string",
  • "card_name": "string",
  • "card_type": "VIRTUAL",
  • "limit_type": "CARD",
  • "spend_controls": {
    },
  • "billing_address": {
    },
  • "mailing_address": {
    },
  • "expiration_date": {
    },
  • "has_been_transferred": true,
  • "metadata": {
    },
  • "budget_id": "string"
}

Get card

Retrieves a card by ID. Only cards with limit_type = CARD have spend_controls

SecurityOAuth2
Request
path Parameters
id
required
string
Responses
200

getCardById 200 response

get/v2/cards/{id}
Request samples
Response samples
application/json
{
  • "id": "string",
  • "owner": {
    },
  • "status": "ACTIVE",
  • "last_four": "string",
  • "card_name": "string",
  • "card_type": "VIRTUAL",
  • "limit_type": "CARD",
  • "spend_controls": {
    },
  • "billing_address": {
    },
  • "mailing_address": {
    },
  • "expiration_date": {
    },
  • "has_been_transferred": true,
  • "metadata": {
    },
  • "budget_id": "string"
}

Update card

Update an existing vendor card

SecurityOAuth2
Request
path Parameters
id
required
string
header Parameters
Idempotency-Key
string or null
Request Body schema: application/json
object or null
object or null

Set of key value pairs associated with this object. Please do not store any personally identifiable or sensitive information here. Limitations: maximum of 50 keys, keys cannot exceed 40 characters, values cannot exceed 500 characters.

Responses
200

updateCard 200 response

put/v2/cards/{id}
Request samples
application/json
{
  • "spend_controls": {
    },
  • "metadata": {
    }
}
Response samples
application/json
{
  • "id": "string",
  • "owner": {
    },
  • "status": "ACTIVE",
  • "last_four": "string",
  • "card_name": "string",
  • "card_type": "VIRTUAL",
  • "limit_type": "CARD",
  • "spend_controls": {
    },
  • "billing_address": {
    },
  • "mailing_address": {
    },
  • "expiration_date": {
    },
  • "has_been_transferred": true,
  • "metadata": {
    },
  • "budget_id": "string"
}

Lock card

Locks an existing, unlocked card. And the card owner will receive a notification about it.

SecurityOAuth2
Request
path Parameters
id
required
string
header Parameters
Idempotency-Key
string or null
Request Body schema: application/json
description
string or null

Description for locking a card

reason
required
string (ChangeCardReason)

Reason for card termination.

Enum: "CARD_DAMAGED" "CARD_LOST" "CARD_NOT_RECEIVED" "DO_NOT_NEED_PHYSICAL_CARD" "DO_NOT_NEED_VIRTUAL_CARD" "FRAUD" "OTHER"
Responses
200

lockCard 200 response

post/v2/cards/{id}/lock
Request samples
application/json
{
  • "description": "string",
  • "reason": "CARD_DAMAGED"
}
Response samples
application/json
{
  • "id": "string",
  • "owner": {
    },
  • "status": "ACTIVE",
  • "last_four": "string",
  • "card_name": "string",
  • "card_type": "VIRTUAL",
  • "limit_type": "CARD",
  • "spend_controls": {
    },
  • "billing_address": {
    },
  • "mailing_address": {
    },
  • "expiration_date": {
    },
  • "has_been_transferred": true,
  • "metadata": {
    },
  • "budget_id": "string"
}

Get card number

Retrieves card number, CVV, and expiration date of a card by ID.

SecurityOAuth2
Request
path Parameters
id
required
string
Responses
200

getCardNumber 200 response

get/v2/cards/{id}/pan
Request samples
Response samples
application/json
{
  • "id": "string",
  • "number": "string",
  • "cvv": "string",
  • "expiration_date": {
    }
}

Create secure email to send card number

Creates a secure email to send card number, CVV, and expiration date of a card by ID to the specified email.

This endpoint is currently gated. If you would like to request access, please reach out to developer-access@brex.com

SecurityOAuth2
Request
path Parameters
id
required
string
header Parameters
Idempotency-Key
required
string
Request Body schema: application/json
recipient_email
string

Email address to send card details to

sender_name
string

Sender name. Shows up in the subject of the email

message
string or null

Message to send with the card details

expiry_days
integer or null <int32> <= 30

Link expiry in number of days. Defaults to 30

Responses
200

emailCardNumber 200 response

post/v2/cards/{id}/secure_email
Request samples
application/json
{
  • "recipient_email": "string",
  • "sender_name": "string",
  • "message": "string",
  • "expiry_days": 30
}

Terminate card

Terminates an existing card. The card owner will receive a notification about it.

SecurityOAuth2
Request
path Parameters
id
required
string
header Parameters
Idempotency-Key
string or null
Request Body schema: application/json
description
string or null

Description for terminating a card

reason
required
string (ChangeCardReason)

Reason for card termination.

Enum: "CARD_DAMAGED" "CARD_LOST" "CARD_NOT_RECEIVED" "DO_NOT_NEED_PHYSICAL_CARD" "DO_NOT_NEED_VIRTUAL_CARD" "FRAUD" "OTHER"
Responses
200

terminateCard 200 response

post/v2/cards/{id}/terminate
Request samples
application/json
{
  • "description": "string",
  • "reason": "CARD_DAMAGED"
}
Response samples
application/json
{
  • "id": "string",
  • "owner": {
    },
  • "status": "ACTIVE",
  • "last_four": "string",
  • "card_name": "string",
  • "card_type": "VIRTUAL",
  • "limit_type": "CARD",
  • "spend_controls": {
    },
  • "billing_address": {
    },
  • "mailing_address": {
    },
  • "expiration_date": {
    },
  • "has_been_transferred": true,
  • "metadata": {
    },
  • "budget_id": "string"
}

Unlock card

Unlocks an existing card.

SecurityOAuth2
Request
path Parameters
id
required
string
header Parameters
Idempotency-Key
string or null
Responses
200

unlockCard 200 response

post/v2/cards/{id}/unlock
Request samples
Response samples
application/json
{
  • "id": "string",
  • "owner": {
    },
  • "status": "ACTIVE",
  • "last_four": "string",
  • "card_name": "string",
  • "card_type": "VIRTUAL",
  • "limit_type": "CARD",
  • "spend_controls": {
    },
  • "billing_address": {
    },
  • "mailing_address": {
    },
  • "expiration_date": {
    },
  • "has_been_transferred": true,
  • "metadata": {
    },
  • "budget_id": "string"
}

Companies

Get company

This endpoint returns the company associated with the OAuth2 access token.

SecurityOAuth2
Responses
200

getCompany 200 response

get/v2/company
Request samples
Response samples
application/json
{
  • "id": "string",
  • "legal_name": "string",
  • "mailing_address": {
    },
  • "accountType": "BREX_CLASSIC"
}
Copyright © Brex 2019–2022. All rights reserved.