Team API (1.0)

Download OpenAPI specification:Download

Admin: developer-access@brex.com URL: https://brex.com

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": {
    },
  • "holder_name": "string"
}

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.