Users

User Object
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
An array of Addresses associated with the user.
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. Timestampformat.
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.
User Role
Changes since API version 2019-02-01
2020-02-13 - Create a User - New route
The route/v2/usersis now deprecated: to create a user you must use/users.
Create a 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 subclaim is the identifier of the subject, i.e. the user. So, whenever you send us a JWT, we extract the subvalue 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
An array of Addresses associated with the user.
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
An Image ID
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);
Retrieve a User
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.
Update a User
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 arrayof Addressesassociated 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],
  [...]
*/
Update a User's Addresses
Parameters
HTTP
Core SDK
Path Parameter
Type
Description
<user_id>
string
User ID
Body Parameters
Type
Description
addresses
array
An arrayof Addressesassociated 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"
  }]
});
Delete a User
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
}
*/
List All Orders for a User
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: [...]
        [...]
    },
    [...]
]
*/
List All Payment Methods for a User
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: {
          [...]
       }
    }
]
*/
List All Subscriptions for a User
Receives a list of all Subscriptions associated with the user.
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,
        [...]
    }
]
*/
Admin Role
*Paths listed above and denoted with a star are accessible to both Users and Admins. Additional Admin Role paths are listed below.
Retrieve a User
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>
Retrieve All Users
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
string
Date field used to filter results. Default is created.
Request --
GET /users 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]",
        [...]
    },
    {
        "_id": {"$oid": "5a25250cd57ba256dgrte432"},
        "first_name": "John",
        "last_name": "Doe",
        "email": "[email protected]",
        [...]
    },
]
builton.users.get().then(page => {
  console.log(page.current); // First page
});
​
/*
[
    User {
        id: '5a25250cd57ba213edcba515',
        first_name: Jane,
        last_name: Doe,
        email: [email protected],
        [...]
    },
    User {
        id: '5a25250cd57ba256dgrte432',
        first_name: John,
        last_name: Doe,
        email: [email protected],
        [...]
    },
]
*/
Update a User
Parameters
HTTP
Node 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 arrayof Addressesassociated 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.
notes
string
Additional notes regarding the user.
image
string
An Image ID
Request --
PUT /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
​
{
  "first_name": "Oliver"
}
Response --
HTTP/1.1 200 OK
Content-Type: application/json
​
{
  "_id":{"$oid":"5a25250cd57ba213edcba515"},
  "first_name":"Oliver",
  "last_name":"Doe",
  "email":"[email protected]",
  [..]
}
builton.users.update('5a25250cd57ba213edcba515', {
  first_name: "Oliver"
});
​
// OR, if you already have a user stored in a variable:
user.update({
  first_name: 'Oliver'
}).then(console.log);
​
/*
User {
  id: '5a25250cd57ba213edcba515',
  first_name: Oliver,
  last_name: Doe,
  email: [email protected],
  [...]
*/
Update a User's Addresses
Parameters
HTTP
Node SDK
Path Parameter
Type
Description
<user_id>
string
User ID
Body Parameters
Type
Description
addresses
array
An arrayof Addressesassociated with the user.
Request --
PUT /users/5a25250cd57ba213edcba515/addresses HTTP/1.1
Content-Type: application/json
Authorization: Bearer <service-account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
​
[   
    {
        "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":"5a25250cd57ba213edcba515"},
    "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.update('5a25250cd57ba213edcba515', {
  addresses: [{