API Docs

User

The User object can be used to manage your own account and to create child accounts. Only a Production API Key can be used to make requests against the Users API.

There are two kinds of accounts. The first is the standard (parent) User object. It represents your account state, settings, and credentials to log in via the website. The second is the child User, which is a User that belongs to a parent.

Balance and recharge values on User objects are expressed in higher precision US Dollars.

Parent Users must be created through the web interface.

Endpoints
GET
/users/:id
PATCH
/users/:id

User object

id
string
Unique, begins with "user_"
object
string
"User"
parent_id
string
The ID of the parent User object. Top-level Users are defined as Users with no parent.
name
string
The first and last name of the user
email
string
An email address for the user
phone_number
string
A phone number for the user
balance
string
Wallet balance. Formatted as string "XX.XXXXX"
price_per_shipment
string
Cost per shipment purchase. Formatted as string "XX.XXXXX"
recharge_amount
string
How much to recharge the user's wallet when the balance drops below the recharge threshold. Formatted as string 'XX.XXXXX'
secondary_recharge_amount
string
How much to recharge the user's wallet when the balance drops below the recharge threshold. Formatted as string 'XX.XXXXX'
recharge_threshold
string
USD cents value that, when your balance drops below, we automatically recharge your account with your primary payment method
cc_fee_rate
string
The fee rate for convenience fees
insurance_fee_rate
string
The fee rate for insurance purchases
insurance_fee_minimum
string
The minimum cost for insurance purchases
children
array
All associated Child Users
User Object
{
  "id": "user_060ab38db3c04ffaa60f262e5781a9be",
  "object": "User",
  "parent_id": null,
  "name": "EasyPost Docs",
  "phone_number": "5555555555",
  "verified": true,
  "created_at": "2022-10-14T17:23:58Z",
  "default_carbon_offset": false,
  "has_elevate_access": false,
  "balance": "0.00000",
  "price_per_shipment": "0.00000",
  "recharge_amount": null,
  "secondary_recharge_amount": null,
  "recharge_threshold": null,
  "has_billing_method": null,
  "cc_fee_rate": "0.0375",
  "default_insurance_amount": null,
  "insurance_fee_rate": "0.005",
  "insurance_fee_minimum": "0.50",
  "email": "dev+easypost-docs@easypost.com",
  "children": [
    {
      "id": "user_0ae8cb7000a1438c8598fa5786fdae84",
      "object": "User",
      "parent_id": "user_060ab38db3c04ffaa60f262e5781a9be",
      "name": "Test User",
      "phone_number": "8005550100",
      "verified": true,
      "created_at": "2022-10-17T17:28:30Z",
      "default_carbon_offset": false,
      "has_elevate_access": false,
      "children": []
    }
  ]
}
Production OnlyThis call will only work with your Production API Key.

Retrieve a User

Each User can be retrieved individually by id. Any id provided must be either the id of the authenticated User or the id of one of its Child Users. Additionally, to retrieve the authenticated User directly, no id is required.

GET /users/:id
1# Retrieve the authenticated user
2curl -X GET https://api.easypost.com/v2/users \
3  -u "EASYPOST_API_KEY":
4
5# Retrieve a child user
6curl -X GET https://api.easypost.com/v2/users/user_... \
7  -u "EASYPOST_API_KEY":
Response
1{
2  "id": "user_060ab38db3c04ffaa60f262e5781a9be",
3  "object": "User",
4  "parent_id": null,
5  "name": "EasyPost Docs",
6  "phone_number": "5555555555",
7  "verified": true,
8  "created_at": "2022-10-14T17:23:58Z",
9  "default_carbon_offset": false,
10  "has_elevate_access": false,
11  "balance": "0.00000",
12  "price_per_shipment": "0.00000",
13  "recharge_amount": null,
14  "secondary_recharge_amount": null,
15  "recharge_threshold": null,
16  "has_billing_method": null,
17  "cc_fee_rate": "0.0375",
18  "default_insurance_amount": null,
19  "insurance_fee_rate": "0.005",
20  "insurance_fee_minimum": "0.50",
21  "email": "dev+easypost-docs@easypost.com",
22  "children": [
23    {
24      "id": "user_0ae8cb7000a1438c8598fa5786fdae84",
25      "object": "User",
26      "parent_id": "user_060ab38db3c04ffaa60f262e5781a9be",
27      "name": "Test User",
28      "phone_number": "8005550100",
29      "verified": true,
30      "created_at": "2022-10-17T17:28:30Z",
31      "default_carbon_offset": false,
32      "has_elevate_access": false,
33      "children": []
34    }
35  ]
36}
Production OnlyThis call will only work with your Production API Key.

Update a User

Just like retrieving a User, they can be updated using the same patterns. Passing an id will allow the update of a Child User or the authenticated User. Passing no id will update the authenticated User.

Since Child Users also have the ability to authenticate themselves, they can be updated without passing an id. Child Users may only have their name field updated; all other fields are ignored.

An update request for a User is a partial update. Only attributes specifically passed in will be updated. The current_password attribute is required when updating email or password.

Request Parameters

password
i.e. "hunter2"
password_confirmation
i.e. "hunter2"
current_password
i.e. "Cthon98"
name
i.e. "Azure Diamond"
phone_number
i.e. "555-867-5309"
recharge_amount
i.e. "100.00"
secondary_recharge_amount
i.e. "50.00"
recharge_threshold
i.e. "20.00"
PATCH /users/:id
1# Update the authenticated user
2curl -X PATCH https://api.easypost.com/v2/users \
3  -u "EASYPOST_API_KEY": \
4  -H 'Content-Type: application/json' \
5  -d '{
6    "user": {
7      "recharge_threshold": "50.00"
8    }
9  }'
10
11# Update a child user
12curl -X PATCH https://api.easypost.com/v2/users/user_... \
13  -u "EASYPOST_API_KEY": \
14  -H 'Content-Type: application/json' \
15  -d '{
16    "user": {
17      "name": "Test Child"
18    }
19  }'
Response
1{
2  "id": "user_060ab38db3c04ffaa60f262e5781a9be",
3  "object": "User",
4  "parent_id": null,
5  "name": "EasyPost Docs",
6  "phone_number": "5555555555",
7  "verified": true,
8  "created_at": "2022-10-14T17:23:58Z",
9  "default_carbon_offset": false,
10  "has_elevate_access": false,
11  "balance": "0.00000",
12  "price_per_shipment": "0.00000",
13  "recharge_amount": null,
14  "secondary_recharge_amount": null,
15  "recharge_threshold": null,
16  "has_billing_method": null,
17  "cc_fee_rate": "0.0375",
18  "default_insurance_amount": null,
19  "insurance_fee_rate": "0.005",
20  "insurance_fee_minimum": "0.50",
21  "email": "dev+easypost-docs@easypost.com",
22  "children": [
23    {
24      "id": "user_0ae8cb7000a1438c8598fa5786fdae84",
25      "object": "User",
26      "parent_id": "user_060ab38db3c04ffaa60f262e5781a9be",
27      "name": "Test User",
28      "phone_number": "8005550100",
29      "verified": true,
30      "created_at": "2022-10-17T17:28:30Z",
31      "default_carbon_offset": false,
32      "has_elevate_access": false,
33      "children": []
34    }
35  ]
36}