Users
Where your customers CRUD is kept.
The User Object holds all the usual info you'd expect, name, phone number, address, etc. You can also add tags to users, which can be used to
search
, and come in handy when you get into our ML tools.Attributes | Type | Description |
first_name | string | First name of the user. |
last_name | string | Last name of the user. |
salutation | string | Title of the user. |
email | string | E-mail of the user. |
mobile_phone_number | string | Phone number of the user. |
addresses | array | |
billing_address | object | Billing Address of the user. |
default_payment_method | string | Default payment method of the user. |
last_login | string | Date when user last logged in. Timestamp format. |
bio | string | Biographical note about the user. |
tags | array | List of tags associated with user. |
note | string | Additional notes regarding the user. |
human_id | string | Human readable ID that identifies the order easily, e.g. 3AG7UA. |
image | object | Image object for this user. |
And on the 6th day, you can make pancakes and watch cartoons, cuz creating new users is super easy. Just use
POST /users
.We use the JWT in the header to identify a User. According to the JWT specs, the
sub
claim is the identifier of the subject, i.e. the user. So, whenever you send us a JWT, we extract the sub
value and use that as the user ID.See Authentication for how to get a JWT. With the route
POST /users
, you could both create a new user with a JWT and login a user with their JWT.Parameters
HTTP
Core SDK
Body Parameters | Type | Description |
first_name | string | First name of the user. |
last_name | string | Last name of the user. |
salutation | string | Title of the user. |
email | string | E-mail of the user. |
mobile_phone_number | string | Phone number of the user. |
addresses | array | |
billing_address | object | Billing Address of the user. |
bio | string | Biographical note about the user. |
tags | array | List of tags associated with the user. |
note | string | Additional notes regarding the user. |
image | string |
Request --
POST /users HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOi
IxMjM0NTY3ODkwIiwibGFzdF9uYW1lIjoiRG9lIiwiZmlyc3RfbmFtZSI6IkpvaG4iLCJ
pYXQiOjE1MTYyMzkwMjJ9.YEqWlNmcheENbeSTjXhA-LMfULwa7t_Ab71tDmLGUxA
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
{
"first_name": "Jone",
"last_name": "Doe",
"email": "[email protected]"
}
Response --
HTTP/1.1 200 OK
Content-Type: application/json
HTTP/1.1 200 OK
Content-Type: application/json
{
"_id": {"$oid": "5a25250cd57ba213edcba515"},
"first_name": "Jane",
"last_name": "Doe",
"email": "[email protected]",
[...]
}
builton.users.create({
first_name: 'Jone',
last_name: 'Doe',
email: '[email protected]',
mobile_phone_number: '+4712345678',
}).then(console.log);
Parameters
HTTP
Core SDK
Path Parameters | Type | Description |
<user_id> | string | User ID |
Request --
GET /users/me HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
Response --
HTTP/1.1 200 OK
Content-Type: application/json
{
"_id": {"$oid": "5a25250cd57ba213edcba515"},
"first_name": "Jane",
"last_name": "Doe",
"email": "[email protected]",
[...]
}
builton.users.get('me').then(console.log);
// OR, if you already have a user stored in a variable:
builton.users.setMe().get().then(console.log);
/*
User {
id: '5a25250cd57ba213edcba515',
first_name: Jane,
last_name: Doe,
email: [email protected],
[...]
*/
To retrieve, update, or delete your currently logged-in user, you can replace the user id in the query parameter with
me
.Parameters
HTTP
Core SDK
Path Parameter | Type | Description |
<user_id> | string | User ID |
Body Parameters | Type | Description |
first_name | string | First name of the user. |
last_name | string | Last name of the user. |
salutation | string | Title of the user. |
email | string | E-mail of the user. |
mobile_phone_number | string | Phone number of the user. |
default_payment_method | string | Default payment method of the user. |
addresses | array | An array of Addresses associated with the user. |
billing_address | object | Address used for billing purposes. |
bio | string | Biographical note about the user. |
tags | array | List of tags associated with the user. |
note | string | Additional notes regarding the user. |
Request --
PUT /users/me HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
{
"first_name": "Oliver"
}
Response --
HTTP/1.1 200 OK
Content-Type: application/json
{
"_id":{"$oid":"57ee9c72d76d431f85111432"},
"first_name":"Oliver",
"last_name":"Doe",
[...]
}
builton.users.setMe().update({
first_name: 'Oliver'
}).then(console.log);
/*
User {
id: '5a25250cd57ba213edcba515',
first_name: Oliver,
last_name: Doe,
email: [email protected],
[...]
*/
Parameters
HTTP
Core SDK
Path Parameter | Type | Description |
<user_id> | string | User ID |
Body Parameters | Type | Description |
addresses | array | An array of Addresses associated with the user. |
Request --
PUT /users/me/addresses HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
{
"addresses": [
{
"city":"Oslo",
"service":"google",
"alias":"",
"country":"Norway",
"zip_code":"0182",
"street_name":"Hausmanns gate 29"
}
]
}
Response --
HTTP/1.1 200 OK
Content-Type: application/json
{
"_id":{"$oid":"57ee9c72d76d431f85111432"},
"first_name":"Oliver",
"last_name":"Doe",
"addresses": [
{
"zip_code": "0182",
"alias": "",
"geo": [
59.91764119999999,
10.7540584
],
"street_name": "Hausmanns gate 29",
"service": "google",
"country": "Norway",
"raw": {
"plus_code": {
"compound_code": "WQ93+3J Oslo, Norway",
"global_code": "9FFGWQ93+3J"
},
"geometry": {
"location": {
"lat": 59.91764119999999,
"lng": 10.7540584
},
"location_type": "ROOFTOP",
"viewport": {
"northeast": {
"lat": 59.9189901802915,
"lng": 10.7554073802915
},
"southwest": {
"lat": 59.91629221970849,
"lng": 10.7527094197085
}
}
},
"types": [
"street_address"
],
"formatted_address": "Hausmanns gate 29, 0182 Oslo, Norway",
"place_id": "ChIJbbryrGZuQUYR812VHuiBKBQ"
},
"service_address_id": "ChIJbbryrGZuQUYR812VHuiBKBQ",
"city": "Oslo"
}
],
[...]
}
builton.users.setMe().update({
addresses: [{
"street_name": "Nadderudåsen 30",
"city": "Bekkestua",
"zip_code": "1357",
"country": "Norway"
}]
});
Parameters
HTTP
Core SDK
Path Parameter | Type | Description |
<user_id> | string | User ID |
Request --
DELETE /users/me HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
Response --
HTTP/1.1 200 OK
Content-Type: application/json
{
"_id":{"$oid":"57ee9c72d76d431f85111432"},
"created":{"$date":1475428903950},
"modified":{"$date":1475428903951},
[...]
"deleted":true
}
builton.users.setMe().del().then(console.log);
/*
User {
id: '57ee9c72d76d431f85111432',
created: {'$date':1475428903950},
modified: {'$date':1475428903951},
[...]
deleted: true
}
*/
Parameters
HTTP
Core SDK
Path Parameter | Type | Description |
<user_id> | string | User ID |
Query Parameters | Type | Description |
size | number | Number of items to retrieve. |
page | number | Which page to retrieve. Default is 10. |
sort | string | Field used for sorting results. Default is created. |
from_date | number | Start date, timestamp format. Default is current date minus 15 days. |
to_date | number | End date, timestamp format. Default is current date plus 15 days. |
date_filter | string | Date field used to filter results. Default is created. |
order_status | string | Orders with a specific status are also listed. Values can be separated by a comma, e.g., success, processing . |
delivery_status | string | Orders with a specific delivery status are also listed. Values can be separated by a comma, e.g., assigned, done, created . |
Request --
GET /users/me/orders HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
Response --
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"_id": {
"$oid": "5c815f19ce39da0008e83eae"
},
"total_amount": 42,
"items": [...]
[...]
},
[...]
]
builton.orders.get().then(page => {
console.log(page.current); // First page
});
/*
[
Order {
id: '5c815f19ce39da0008e83eae',
total_amount: 42,
items: [...]
[...]
},
[...]
]
*/
Parameters
HTTP
Core SDK
Path Parameter | Type | Description |
<user_id> | string | User ID |
Query Parameters | Type | Description |
size | number | Number of items to retrieve. |
page | number | Which page to retrieve. Default is 10. |
sort | string | Field used for sorting results. Default is created. |
from_date | number | Start date, timestamp format. Default is current date minus 15 days. |
to_date | number | End date, timestamp format. Default is current date plus 15 days. |
date_filter | string | Date field used to filter results. Default is created. |
Request --
GET /users/me/payment_methods HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
Response --
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"_id":{"$oid":"57ee9c43d75d241d82231433"},
"active":true,
"user":{"$oid":"57ee9c72d76d431f85111432"},
"method":"stripe",
[...]
"card":{
[...]
}
}
]
builton.paymentMethods.get().then(page => {
console.log(page.current); // First page
});
/*
[
paymentMethod {
id: '57ee9c43d75d241d82231433'
active: true,
user: {$oid: '57ee9c72d76d431f85111432'},
method: 'stripe',
[...]
card: {
[...]
}
}
]
*/
Parameters
HTTP
Core SDK
Path Parameter | Type | Description |
<user_id> | string | User ID |
Query Parameters | Type | Description |
include_deleted | boolean | If true , the request also returns all deleted subscriptions. |
size | number | Number of subscriptions per page. Default is 10. |
page | number | Which page to retrieve. Default is 0. |
sort | string | Field used to sort results. Default is -modified. |
status | string | The subscription status Default is ACTIVE. |
Request --
GET /users/me/subscriptions HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
Response --
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"_id": {
"$oid": "5b570317a5f4b4000b6618dc"
},
"plan": {
"$oid": "5b3b77dd1884cc00086ebbc7"
},
"method": "license",
"throttling_starts": 1000,
"name": "LICENSE",
"status": "CREATED",
"is_retrying_payment": false,
"infinite": false,
"total_fail_attempts": 0,
"payments": [],
"user": {
"$oid": "5b55ba2c89dff8000d0d5c29"
},
"trial": false,
[...]
},
{
"_id": {
"$oid": "5b570604a5f4b400086612da"
},
"plan": {
"$oid": "5b3b77dd1884cc00086ebbc7"
},
"method": "license",
"throttling_starts": 1000,
"name": "LICENSE",
"status": "CREATED",
"is_retrying_payment": false,
"infinite": false,
"total_fail_attempts": 0,
"payments": [],
"user": {
"$oid": "5b55ba2c89dff8000d0d5c29"
},
"trial": false,
[...]
}
]
builton.subscriptions.get().then(page => {
console.log(page.current); // First page
});
/*
[
Subscription {
id: '5b570317a5f4b4000b6618dc',
plan: {
'$oid': '5b3b77dd1884cc00086ebbc7'
},
method: 'license',
throttling_starts: 1000,
name: 'LICENSE',
status: 'CREATED',
is_retrying_payment: false,
infinite: false,
total_fail_attempts: 0,
payments: [],
user: {
'$oid': '5b55ba2c89dff8000d0d5c29'
},
trial: false,
[...]
},
Subscription {
'_id': {
'$oid': '5b570604a5f4b400086612da'
},
'plan': {
'$oid': '5b3b77dd1884cc00086ebbc7'
},
'method': 'license',
'throttling_starts': 1000,
'name': 'LICENSE',
'status': 'CREATED',
'is_retrying_payment': false,
'infinite': false,
'total_fail_attempts': 0,
'payments': [],
'user': {
'$oid': '5b55ba2c89dff8000d0d5c29'
},
'trial': false,
[...]
}
]
*/
*Paths listed above and denoted with a star are accessible to both Users and Admins. Additional Admin Role paths are listed below.
Parameters
HTTP
Node SDK
Python SDK
Path Parameter | Type | Description |
<user_id> | string | User ID |
Request --
GET /users/5a25250cd57ba213edcba515 HTTP/1.1
Content-Type: application/json
Authorization: Bearer <service-account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
Response --
HTTP/1.1 200 OK
Content-Type: application/json
{
"_id": {"$oid": "5a25250cd57ba213edcba515"},
"first_name": "Jane",
"last_name": "Doe",
"email": "[email protected]",
[...]
}
builton.users.get('5a25250cd57ba213edcba515').then(console.log);
/*
User {
id: '5a25250cd57ba213edcba515',
first_name: Jane,
last_name: Doe,
email: [email protected],
[...]
}
*/
user = builton.user().get('5a25250cd57ba213edcba515')
print(user)
# <User 5a25250cd57ba213edcba515>
Parameters
HTTP
Node SDK
Query Parameters | Type | Description |
size | number | Number of items to retrieve. |
page | number | Which page to retrieve. Default is 10. |
sort | string | Field used for sorting results. Default is created. |
from_date | number | Start date, timestamp format. Default is current date minus 15 days. |
to_date | number | End date, timestamp format. Default is current date plus 15 days. |
date_filter |