Team API (0.1)

Download OpenAPI specification:Download

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

Authentication

OAuth2

OAuth2 security scheme

Security Scheme Type OAuth2
authorizationCode OAuth Flow
Authorization URL: https://accounts.brex.com/oauth2/v1/auth
Token URL: https://accounts.brex.com/oauth2/v1/token
Scopes:
  • openid -

    openid

  • offline_access -

    offline access

  • users.readonly -

    View user data

  • users -

    View and manage user data

  • locations.readonly -

    View location data

  • locations -

    View and manage location data

  • departments.readonly -

    View department data

  • departments -

    View and manage department data

  • cards -

    View and manage card data

  • cards.readonly -

    View card data

  • cards.pan -

    View card number data

Users

Endpoints for user management.

List users

This endpoint lists all users.

Request
Security:
OAuth2 (usersusers.readonly)
query Parameters
cursor
string or null
limit
integer or null <int32>
email
string or null
Responses
200

listUsers 200 response

400

Bad request

401

Unauthorized

403

Forbidden

get/v2/users
Request samples
curl -i -X GET \
  https://platform.brexapis.com/v2/users \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
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.

Request
Security:
OAuth2 (users)
header Parameters
Idempotency-Key
string
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
Responses
200

createUser 200 response

400

Bad request

401

Unauthorized

403

Forbidden

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"
}
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"
}

Get current user

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

Request
Security:
OAuth2 (usersusers.readonly)
Responses
200

getMe 200 response

400

Bad request

401

Unauthorized

403

Forbidden

get/v2/users/me
Request samples
curl -i -X GET \
  https://platform.brexapis.com/v2/users/me \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
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"
}

Get user

This endpoint gets a user by ID.

Request
Security:
OAuth2 (usersusers.readonly)
path Parameters
id
required
string
Responses
200

getUserById 200 response

400

Bad request

401

Unauthorized

403

Forbidden

get/v2/users/{id}
Request samples
curl -i -X GET \
  https://platform.brexapis.com/v2/users/:id \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
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"
}

Update user

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

Request
Security:
OAuth2 (users)
header Parameters
Idempotency-Key
string
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
Responses
200

updateUser 200 response

400

Bad request

401

Unauthorized

403

Forbidden

put/v2/users/{id}
Request samples
application/json
{
  • "status": "ACTIVE",
  • "manager_id": "string",
  • "department_id": "string",
  • "location_id": "string"
}
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"
}

Get limit for the user

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

Request
Security:
OAuth2 (usersusers.readonly)
path Parameters
id
required
string
Responses
200

getUserLimit 200 response

get/v2/users/{id}/limit
Request samples
curl -i -X GET \
  https://platform.brexapis.com/v2/users/:id/limit \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
Response samples
application/json
{
  • "monthly_limit": {
    }
}

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.

Request
Security:
OAuth2 (users)
header Parameters
Idempotency-Key
string
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).

Responses
200

setUserLimit 200 response

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

Locations

Endpoints for location management.

List locations

This endpoint lists all locations.

Request
Security:
OAuth2 (locationslocations.readonly)
query Parameters
cursor
string or null
limit
integer or null <int32>
name
string or null
Responses
200

listLocations 200 response

400

Bad request

401

Unauthorized

403

Forbidden

get/v2/locations
Request samples
curl -i -X GET \
  https://platform.brexapis.com/v2/locations \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
Response samples
application/json
{
  • "next_cursor": "string",
  • "items": [
    ]
}

Create location

This endpoint creates a new location.

Request
Security:
OAuth2 (locations)
header Parameters
Idempotency-Key
string
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

400

Bad request

401

Unauthorized

403

Forbidden

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.

Request
Security:
OAuth2 (locationslocations.readonly)
path Parameters
id
required
string
Responses
200

getLocationById 200 response

400

Bad request

401

Unauthorized

403

Forbidden

get/v2/locations/{id}
Request samples
curl -i -X GET \
  https://platform.brexapis.com/v2/locations/:id \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
Response samples
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string"
}

Departments

Endpoints for department management.

List departments

This endpoint lists all departments.

Request
Security:
OAuth2 (departmentsdepartments.readonly)
query Parameters
cursor
string or null
limit
integer or null <int32>
name
string or null
Responses
200

listDepartments 200 response

400

Bad request

401

Unauthorized

403

Forbidden

get/v2/departments
Request samples
curl -i -X GET \
  https://platform.brexapis.com/v2/departments \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
Response samples
application/json
{
  • "next_cursor": "string",
  • "items": [
    ]
}

Create department

This endpoint creates a new department

Request
Security:
OAuth2 (departments)
header Parameters
Idempotency-Key
string
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

400

Bad request

401

Unauthorized

403

Forbidden

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.

Request
Security:
OAuth2 (departmentsdepartments.readonly)
path Parameters
id
required
string
Responses
200

getDepartmentById 200 response

400

Bad request

401

Unauthorized

403

Forbidden

get/v2/departments/{id}
Request samples
curl -i -X GET \
  https://platform.brexapis.com/v2/departments/:id \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
Response samples
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string"
}

Cards

Endpoints for card management.

List cards

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

Request
Security:
OAuth2 (cards.readonlycards)
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
curl -i -X GET \
  https://platform.brexapis.com/v2/cards \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
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 the first 2 lines of the address must be under 60 characters long. Each user can only have up to 10 active physical cards.

Request
Security:
OAuth2 (cards)
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).

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": {
    }
}
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": {
    }
}

Get card

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

Request
Security:
OAuth2 (cardscards.readonly)
path Parameters
id
required
string
Responses
200

getCardById 200 response

get/v2/cards/{id}
Request samples
curl -i -X GET \
  https://platform.brexapis.com/v2/cards/:id \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
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": {
    }
}

Update card

Update an existing vendor card

Request
Security:
OAuth2 (cards)
header Parameters
Idempotency-Key
string
Request Body schema: application/json
object or null
Responses
200

updateCard 200 response

put/v2/cards/{id}
Request samples
application/json
{
  • "spend_controls": {
    }
}
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": {
    }
}

Lock card

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

Request
Security:
OAuth2 (cards)
header Parameters
Idempotency-Key
string
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": {
    }
}

Get card number

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

Request
Security:
OAuth2 (cards.pan)
path Parameters
id
required
string
Responses
200

getCardNumber 200 response

get/v2/cards/{id}/pan
Request samples
curl -i -X GET \
  https://platform.brexapis.com/v2/cards/:id/pan \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
Response samples
application/json
{
  • "id": "string",
  • "number": "string",
  • "cvv": "string",
  • "expiration_date": {
    }
}

Terminate card

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

Request
Security:
OAuth2 (cards)
header Parameters
Idempotency-Key
string
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": {
    }
}

Unlock card

Unlocks an existing card.

Request
Security:
OAuth2 (cards)
header Parameters
Idempotency-Key
string
Request Body schema: application/json
object
Responses
200

unlockCard 200 response

post/v2/cards/{id}/unlock
Request samples
application/json
{ }
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": {
    }
}

Companies

Get company

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

Request
Security:
OAuth2 (companies.readonly)
Responses
200

getCompany 200 response

400

Bad request

401

Unauthorized

403

Forbidden

get/v2/company
Request samples
curl -i -X GET \
  https://platform.brexapis.com/v2/company \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
Response samples
application/json
{
  • "id": "string",
  • "legal_name": "string",
  • "mailing_address": {
    }
}
Copyright © Brex 2019–2021. All rights reserved.