Users

Where your customers CRUD is kept.

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.
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 /v2/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 /v2/users, you could both create a new user with a JWT and login a user with their JWT.
Parameters
Request (with example JWT)
Response
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.
POST /v2/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": "jane@email.com",
   "mobile_phone_number": "+4712345678",
   "addresses": [{
               "city":"Danielsen",
               "service":"google",
               "alias":"",
               "country":"Paraguay",
               "zip_code":"0556",
               "state":"Oslo",
               "street_name":"Streetname 7"
             }]
}
HTTP/1.1 200 OK
Content-Type: application/json
​
{
    "roles": ["user"],
    "tags": [],
    "auth0_id": "some-id",
    "mobile_phone_number": "+4712345678",
    "billing_address":
        {"service": "google",
        "alias": " "},
    "voucher": {"uuid": "b498e02b-2031-4d84-b55b-b460d22f44b4",
                "consumed": 0,
                "initial_quantity": 0,
                "created": {"$date": 1512383756277},
                "expires": {"$date": 1543919756277}},
    "_cls": "User",
    "created": {"$date": 1512383756277},
    "addresses":
        [{"zip_code": "0556",
        "city": "Danielsen",
        "street_name": "Streetname 7",
        "country": "Paraguay",
        "alias": " ",
        "service": "google"}],
    "company": {"$oid": "57ee9c71d76d431f8511142f"},
    "email": "jane@email.com",
    "national_id": "1234567890",
    "modified": {"$date": 1512383756279},
    "avatar": " ",
    "bio": " ",
    "stripe_customer_id": " ",
    "note": " ",
    "first_name": "Jane",
    "_id": {"$oid": "5a25250cd57ba213edcba515"},
    "new_customer": true,
    "last_name": "Doe",
    "last_login": {"$date": 1512383756278},
    "deleted": false,
    "voucher": {}
}
Retrieve a User
Parameters
Request
Response
Path Parameter
Type
Description
me
string
Current user's id supplied with parameter me
GET /users/me HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
HTTP/1.1 200 OK
Content-Type: application/json
​
{
  "_id":{"$oid":"57ee9c72d76d431f85111432"},
  "_cls":"User",
  "created":{"$date":1475428903950},
  "modified":{"$date":1475428903951},
  "first_name":"Jane",
  "last_name":"Doe",
  "email":"jane@email.com",
  "mobile_phone_number":"+4712345678",
  "addresses":[{
                "city":"Danielsen",
                "service":"google",
                "alias":"",
                "country":"Paraguay",
                "zip_code":"0556",
                "state":"Oslo",
                "street_name":"Iversenstien 7"
             }],
  "billing_address":{},
  "bio":"",
  "note":"",
  "avatar":"",
  "company":{"$oid":"57ee9c71d76d431f8511142f"},
  "tags":[],
  "stripe_customer_id":"",
  "roles":["user"],
  "deleted":false,
  "voucher": {}
}
Update a User
Parameters
Request
Response
Path Parameter
Type
Description
me
string
Current user's id supplied with parameter me.
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.
bio
string
Biographical note about the user.
tags
array
List of tags associated with the user.
note
string
Additional notes regarding the user.
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"
}
HTTP/1.1 200 OK
Content-Type: application/json
​
{
  "_id":{"$oid":"57ee9c72d76d431f85111432"},
  "_cls":"User",
  "created":{"$date":1475428903950},
  "modified":{"$date":1475428903951},
  "first_name":"Oliver",
  "last_name":"Doe",
  "email":"john@email.com",
  "mobile_phone_number":"+4712345678",
  "addresses":[{
                "city":"Danielsen",
                "service":"google",
                "alias":"",
                "country":"Paraguay",
                "zip_code":"0556",
                "state":"Oslo",
                "street_name":"Iversenstien 7"
             }],
  "billing_address":{},
  "bio":"",
  "note":"",
  "avatar":"",
  "company":{"$oid":"57ee9c71d76d431f8511142f"},
  "tags":[],
  "stripe_customer_id":"",
  "roles":["user"],
  "deleted":false,
  "voucher": {}
}
Update a User's Addresses
Parameters
Request
Response
Path Parameter
Type
Description
me
string
Current user's id supplied with parameter me.
Body Parameters
Type
Description
addresses
array
An array of Addresses associated with the user.
billing_address
object
Billing Address of the user.
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
​
[   
    {
        "city":"Oslo",
        "service":"google",
        "alias":"",
        "country":"Norway",
        "zip_code":"0182",
        "street_name":"Hausmanns gate 29"
    }
]
HTTP/1.1 200 OK
Content-Type: application/json
​
{
    "avatar": "",
    "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"
        }
    ],
    "company": {
        "$oid": "59ce1e0a9d3bde0006fa45a9"
    },
    "voucher": {
        "expires": {
            "$date": 1544620115557
        },
        "consumed": 0,
        "initial_quantity": 0,
        "created": {
            "$date": 1513084115556
        },
        "uuid": "76de3268-2a84-4c5c-8434-7903cba42c6a"
    },
    "tags": [],
    "deleted": false,
    "bio": "",
    "modified": {
        "$date": 1553265348157
    },
    "last_login": {
        "$date": 1513084115559
    },
    "auth_id": "",
    "note": "",
    "_id": {
        "$oid": "5a2fd4d3ca79e20013ffc7c8"
    },
    "blocked": false,
    "is_company": false,
    "billing_address": {
        "alias": "",
        "service": "google"
    },
    "new_customer": true,
    "stripe_customer_id": "",
    "_cls": "User",
    "receive_notifications": true,
    "last_name": "",
    "roles": [
        "user"
    ],
    "first_name": "TestCircular",
    "created": {
        "$date": 1513084115556
    },
    "national_id": ""
}
Delete a User
Parameters
Request
Response
Body Parameter
Type
Description
me
string
Current user's id supplied by parameter me.
DELETE /users/me HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
HTTP/1.1 200 OK
Content-Type: application/json
​
{
  "_id":{"$oid":"57ee9c72d76d431f85111432"},
  "_cls":"User",
  "created":{"$date":1475428903950},
  "modified":{"$date":1475428903951},
  "first_name":"John",
  "last_name":"Doe",
  "email":"john@email.com",
  "mobile_phone_number":"+4712345678",
  "addresses":[{
                "city":"Danielsen",
                "service":"google",
                "alias":"",
                "country":"Paraguay",
                "zip_code":"0556",
                "state":"Oslo",
                "street_name":"Iversenstien 7"
             }],
  "billing_address":{},
  "default_payment_method":{"$oid":"62ee9c72d76d431f85111432"},
  "bio":"",
  "note":"",
  "avatar":"",
  "company":{"$oid":"57ee9c71d76d431f8511142f"},
  "tags":[],
  "stripe_customer_id":"",
  "roles":["user"],
  "deleted":true,
  "voucher": {}
}
List All Orders for a User
Parameters
Request
Response
Path Parameter
Type
Description
me
string
Current user's id supplied by parameter me.
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.
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
HTTP/1.1 200 OK
Content-Type: application/json
​
{
        "currency": "NOK",
        "delivery_status": "PENDING",
        "company": {
            "$oid": "59ce1e0a9d3bde0006fa45a9"
        },
        "human_id": "Q22772",
        "deliveries": [],
        "resources": [],
        "deleted": false,
        "modified": {
            "$date": 1551982361556
        },
        "units": 0,
        "total_quantity": 0,
        "note": "some type of note",
        "total_amount": 0,
        "_id": {
            "$oid": "5c815f19ce39da0008e83eae"
        },
        "stripe_refund_id": "",
        "order_status": "CREATED",
        "override_company_take": -1,
        "payments": [],
        "top_up_amount": 0,
        "user": {
            "avatar": "",
            "addresses": [],
            "company": {
                "$oid": "59ce1e0a9d3bde0006fa45a9"
            },
            "voucher": {
                "expires": {
                    "$date": 1544618653657
                },
                "consumed": 0,
                "initial_quantity": 0,
                "created": {
                    "$date": 1513082653657
                },
                "uuid": "76de3268-2a84-4c5c-8434-7903cba42c6a"
            },
            "tags": [],
            "deleted": false,
            "bio": "",
            "modified": {
                "$date": 1513082653658
            },
            "last_login": {
                "$date": 1513082653658
            },
            "auth_id": "",
            "note": "",
            "_id": {
                "$oid": "5a2fcf1dca79e20013ffc7ad"
            },
            "is_company": false,
            "billing_address": {
                "alias": "",
                "service": "google"
            },
            "$oid": "5a2fcf1dca79e20013ffc7ad",
            "new_customer": true,
            "stripe_customer_id": "",
            "_cls": "User",
            "receive_notifications": true,
            "last_name": "",
            "first_name": "TestUser",
            "created": {
                "$date": 1513082653656
            },
            "national_id": ""
        },
        "items": [],
        "stripe_charge_id": "",
        "top_up_vat": 0,
        "created": {
            "$date": 1551982361555
        }
    }
List All Payment Methods for a User
Parameters
Request
Response
Path Parameter
Type
Description
me
string
Current user's id supplied by parameter me.
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.
http 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
HTTP/1.1 200 OK
Content-Type: application/json
[
    {
       "_id":{"$oid":<payment-method-id>},
       "_cls":"PaymentMethod.StripePaymentMethod",
       "created":{"$date":1538058324877},
       "modified":{"$date":1538058327405},
       "deleted":false,
       "active":true,
       "user":{"$oid":"57ee9c72d76d431f85111432"},
       "company":{"$oid":"591ee15db70e2a10acb65362"},
       "name":"Stripe",
       "method":"stripe",
       "token":"tok_1DF0QiEeeXxFpLJtthyCQWVz",
       "customer_id":"cus_DgNBPtNphW2W7r",
       "card":{
          "id":"card_1DF0QiEeeXxFpLJtg4AE1T5z",
          "object":"card",
          "address_city":null,
          "address_country":null,
          "address_line1":null,
          "address_line1_check":null,
          "address_line2":null,
          "address_state":null,
          "address_zip":null,
          "address_zip_check":null,
          "brand":"Visa",
          "country":"US",
          "cvc_check":"unchecked",
          "dynamic_last4":null,
          "exp_month":12,
          "exp_year":2019,
          "fingerprint":"npPw68vQg1usKUWb",
          "funding":"credit",
          "last4":"4242",
          "metadata":{},
          "name":null,
          "tokenization_method":null
       }
    }
]
List All Subscriptions for a User
Receives a list of all Subscriptions associated with the user. 
Parameters
Request
Response
Path Parameter
Type
Description
me
string
Current user's id supplied by parameter me.
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.
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
[    
    {
        "total_payment_retries": 0,
        "company": {
            "$oid": "5b23b5608d8d0c0006a61811"
        },
        "_id": {
            "$oid": "5b570317a5f4b4000b6618dc"
        },
        "prorate_amount": 0,
        "plan": {
            "$oid": "5b3b77dd1884cc00086ebbc7"
        },
        "updated": {
            "$date": 1532429079834
        },
        "method": "license",
        "deleted": false,
        "throttling_starts": 1000,
        "name": "LICENSE",
        "created": {
            "$date": 1532429079834
        },
        "status": "CREATED",
        "is_retrying_payment": false,
        "infinite": false,
        "_cls": "SubscriptionMethod.LicenseSubscription",
        "total_fail_attempts": 0,
        "payments": [],
        "active": true,
        "user": {
            "$oid": "5b55ba2c89dff8000d0d5c29"
        },
        "trial": false
    },
    {
        "total_payment_retries": 0,
        "company": {
            "$oid": "5b23b5608d8d0c0006a61811"
        },
        "_id": {
            "$oid": "5b570604a5f4b400086612da"
        },
        "prorate_amount": 0,
        "plan": {
            "$oid": "5b3b77dd1884cc00086ebbc7"
        },
        "updated": {
            "$date": 1532429828636
        },
        "method": "license",
        "deleted": false,
        "throttling_starts": 1000,
        "name": "LICENSE",
        "created": {
            "$date": 1532429828637
        },
        "status": "CREATED",
        "is_retrying_payment": false,
        "infinite": false,
        "_cls": "SubscriptionMethod.LicenseSubscription",
        "total_fail_attempts": 0,
        "payments": [],
        "active": true,
        "user": {
            "$oid": "5b55ba2c89dff8000d0d5c29"
        },
        "trial": false
    }
]

Nuts & Bolts - Previous

Addresses

Next - Building Blocks

Products

Last updated 2 months ago

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. `Timestamp`format.
`bio`	`string`	Biographical note about the user.
`tags`	`array`	List of tags associated with user.
`note`	`string`	Additional notes regarding the user.

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.

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.
`bio`	`string`	Biographical note about the user.
`tags`	`array`	List of tags associated with the user.
`note`	`string`	Additional notes regarding the user.

Body Parameters	Type	Description
`addresses`	`array`	An `array` of `Addresses` associated with the user.
`billing_address`	`object`	Billing `Address` of the user.

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`.

Path Parameter	Type	Description
`me`	`string`	Current user's id supplied with parameter `me`

Body Parameter	Type	Description
`me`	`string`	Current user's id supplied by parameter `me.`