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 of the user. |
|
| Last name of the user. |
|
| Title of the user. |
|
| E-mail of the user. |
|
| Phone number of the user. |
|
| An |
|
| Billing |
|
| Default payment method of the user. |
|
| Date when user last logged in. |
|
| Biographical note about the user. |
|
| List of tags associated with user. |
|
| Additional notes regarding the user. |
|
| Human readable ID that identifies the order easily, e.g. |
|
|
|
Changes since API version 2019-02-01
The route/v2/users
is now deprecated: to create a user you must use/users.
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.
Body Parameters | Type | Description |
|
| First name of the user. |
|
| Last name of the user. |
|
| Title of the user. |
|
| E-mail of the user. |
|
| Phone number of the user. |
|
| An |
|
| Billing |
|
| Biographical note about the user. |
|
| List of tags associated with the user. |
|
| Additional notes regarding the user. |
|
| An |
Request --POST /users HTTP/1.1Content-Type: application/jsonAuthorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibGFzdF9uYW1lIjoiRG9lIiwiZmlyc3RfbmFtZSI6IkpvaG4iLCJpYXQiOjE1MTYyMzkwMjJ9.YEqWlNmcheENbeSTjXhA-LMfULwa7t_Ab71tDmLGUxAX-Builton-Api-Key: <builton-api-key>Host: api.builton.dev​{"first_name": "Jone","last_name": "Doe","email": "jane@email.com"}
Response --HTTP/1.1 200 OKContent-Type: application/jsonHTTP/1.1 200 OKContent-Type: application/json​{"_id": {"$oid": "5a25250cd57ba213edcba515"},"first_name": "Jane","last_name": "Doe","email": "jane@email.com",[...]}
builton.users.create({first_name: 'Jone',last_name: 'Doe',email: 'jane@email.com',mobile_phone_number: '+4712345678',}).then(console.log);
Path Parameters | Type | Description |
|
| User ID |
Request --GET /users/me HTTP/1.1Content-Type: application/jsonAuthorization: Bearer <jwt>X-Builton-Api-Key: <builton-api-key>Host: api.builton.dev
Response --HTTP/1.1 200 OKContent-Type: application/json​{"_id": {"$oid": "5a25250cd57ba213edcba515"},"first_name": "Jane","last_name": "Doe","email": "jane@email.com",[...]}
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: jane@email.com,[...]*/
To retrieve, update, or delete your currently logged-in user, you can replace the user id in the query parameter with me
.
Path Parameter | Type | Description |
|
| User ID |
Body Parameters | Type | Description |
|
| First name of the user. |
|
| Last name of the user. |
|
| Title of the user. |
|
| E-mail of the user. |
|
| Phone number of the user. |
|
| Default payment method of the user. |
|
| An |
|
|
|
|
| Biographical note about the user. |
|
| List of tags associated with the user. |
|
| Additional notes regarding the user. |
Request --PUT /users/me HTTP/1.1Content-Type: application/jsonAuthorization: Bearer <jwt>X-Builton-Api-Key: <builton-api-key>Host: api.builton.dev​{"first_name": "Oliver"}
Response --HTTP/1.1 200 OKContent-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: jane@email.com,[...]*/
Path Parameter | Type | Description |
|
| User ID |
Body Parameters | Type | Description |
|
| An |
Request --PUT /users/me/addresses HTTP/1.1Content-Type: application/jsonAuthorization: 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 OKContent-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"}]});
Path Parameter | Type | Description |
|
| User ID |
Request --DELETE /users/me HTTP/1.1Content-Type: application/jsonAuthorization: Bearer <jwt>X-Builton-Api-Key: <builton-api-key>Host: api.builton.dev
Response --HTTP/1.1 200 OKContent-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}*/
Path Parameter | Type | Description |
|
| User ID |
Query Parameters | Type | Description |
|
| Number of items to retrieve. |
|
| Which page to retrieve. Default is 10. |
|
| Field used for sorting results. Default is |
|
| Start date, |
|
| End date, |
|
| Date field used to filter results. Default is |
|
| Orders with a specific status are also listed. Values can be separated by a comma, e.g., |
|
| Orders with a specific delivery status are also listed. Values can be separated by a comma, e.g., |
Request --GET /users/me/orders HTTP/1.1Content-Type: application/jsonAuthorization: Bearer <jwt>X-Builton-Api-Key: <builton-api-key>Host: api.builton.dev
Response --HTTP/1.1 200 OKContent-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: [...][...]},[...]]*/
Path Parameter | Type | Description |
|
| User ID |
Query Parameters | Type | Description |
|
| Number of items to retrieve. |
|
| Which page to retrieve. Default is 10. |
|
| Field used for sorting results. Default is |
|
| Start date, |
|
| End date, |
|
| Date field used to filter results. Default is |
Request --GET /users/me/payment_methods HTTP/1.1Content-Type: application/jsonAuthorization: Bearer <jwt>X-Builton-Api-Key: <builton-api-key>Host: api.builton.dev
Response --HTTP/1.1 200 OKContent-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: {[...]}}]*/
Receives a list of all Subscriptions associated with the user.
Path Parameter | Type | Description |
|
| User ID |
Query Parameters | Type | Description |
include_deleted |
| If |
size |
| Number of subscriptions per page. Default is 10. |
page |
| Which page to retrieve. Default is 0. |
sort |
| Field used to sort results. Default is |
status |
| The subscription status Default is |
Request --GET /users/me/subscriptions HTTP/1.1Content-Type: application/jsonAuthorization: Bearer <jwt>X-Builton-Api-Key: <builton-api-key>Host: api.builton.dev
Response --HTTP/1.1 200 OKContent-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.
Path Parameter | Type | Description |
|
| User ID |
Request --GET /users/5a25250cd57ba213edcba515 HTTP/1.1Content-Type: application/jsonAuthorization: Bearer <service-account-key>X-Builton-Api-Key: <builton-api-key>Host: api.builton.dev
Response --HTTP/1.1 200 OKContent-Type: application/json​{"_id": {"$oid": "5a25250cd57ba213edcba515"},"first_name": "Jane","last_name": "Doe","email": "jane@email.com",[...]}
builton.users.get('5a25250cd57ba213edcba515').then(console.log);​/*User {id: '5a25250cd57ba213edcba515',first_name: Jane,last_name: Doe,email: jane@email.com,[...]}*/
user = builton.user().get('5a25250cd57ba213edcba515')print(user)​# <User 5a25250cd57ba213edcba515>
Query Parameters | Type | Description |
|
| Number of items to retrieve. |
|
| Which page to retrieve. Default is 10. |
|
| Field used for sorting results. Default is |
|
| Start date, |
|
| End date, |
|
| Date field used to filter results. Default is |
Request --GET /users HTTP/1.1Content-Type: application/jsonAuthorization: Bearer <service-account-key>X-Builton-Api-Key: <builton-api-key>Host: api.builton.dev
Response --HTTP/1.1 200 OKContent-Type: application/json​[{"_id": {"$oid": "5a25250cd57ba213edcba515"},"first_name": "Jane","last_name": "Doe","email": "jane@email.com",[...]},{"_id": {"$oid": "5a25250cd57ba256dgrte432"},"first_name": "John","last_name": "Doe","email": "john@email.com",[...]},]
builton.users.get().then(page => {console.log(page.current); // First page});​/*[User {id: '5a25250cd57ba213edcba515',first_name: Jane,last_name: Doe,email: jane@email.com,[...]},User {id: '5a25250cd57ba256dgrte432',first_name: John,last_name: Doe,email: john@email.com,[...]},]*/
Path Parameter | Type | Description |
|
| User ID |
Body Parameters | Type | Description |
|
| First name of the user. |
|
| Last name of the user. |
|
| Title of the user. |
|
| E-mail of the user. |
|
| Phone number of the user. |
|
| Default payment method of the user. |
|
| An |
|
|
|
|
| Biographical note about the user. |
|
| List of tags associated with the user. |
|
| Additional notes regarding the user. |
|
| An |
Request --PUT /users/5a25250cd57ba213edcba515 HTTP/1.1Content-Type: application/jsonAuthorization: Bearer <service-account-key>X-Builton-Api-Key: <builton-api-key>Host: api.builton.dev​{"first_name": "Oliver"}
Response --HTTP/1.1 200 OKContent-Type: application/json​{"_id":{"$oid":"5a25250cd57ba213edcba515"},"first_name":"Oliver","last_name":"Doe","email":"john@email.com",[..]}
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: jane@email.com,[...]*/
Path Parameter | Type | Description |
|
| User ID |
Body Parameters | Type | Description |
|
| An |
Request --PUT /users/5a25250cd57ba213edcba515/addresses HTTP/1.1Content-Type: application/jsonAuthorization: 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 OKContent-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: [{"street_name": "Nadderudåsen 30","city": "Bekkestua","zip_code": "1357","country": "Norway"}]});​// OR, if you already have a user stored in a variable:user.update({addresses: [{"street_name": "Nadderudåsen 30","city": "Bekkestua","zip_code": "1357","country": "Norway"}]});
Path Parameters | Type | Description |
|
| User ID |
Request --DELETE /users/5a25250cd57ba213edcba515 HTTP/1.1Content-Type: application/jsonAuthorization: Bearer <service-account-key>X-Builton-Api-Key: <builton-api-key>Host: api.builton.dev
Response --HTTP/1.1 200 OKContent-Type: application/json​{"_id":{"$oid":"5a25250cd57ba213edcba515"},"first_name":"Oliver","last_name":"Doe","email":"john@email.com","deleted":true,[..]}
builton.users.del('5a25250cd57ba213edcba515').then(console.log);​/*User {id: '5a25250cd57ba213edcba515',created: {'$date':1475428903950},modified: {'$date':1475428903951},[...]deleted: true}*/
Path Parameters | Type | Description |
|
| User ID |
Query Parameters | Type | Description |
|
| Number of items to retrieve. |
|
| Which page to retrieve. Default is 10. |
|
| Field used for sorting results. Default is |
|
| Start date, |
|
| End date, |
|
| Date field used to filter results. Default is |
|
| Orders with a specific status are also listed. Values can be separated by a comma, e.g., |
|
| Orders with a specific delivery status are also listed. Values can be separated by a comma, e.g., |
Request --GET /users/5a25250cd57ba213edcba515/orders HTTP/1.1Content-Type: application/jsonAuthorization: Bearer <service-account-key>X-Builton-Api-Key: <builton-api-key>Host: api.builton.dev
Response --HTTP/1.1 200 OKContent-Type: application/json​[{"_id": {"$oid": "5c815f19ce39da0008e83eae"},"total_amount": 42,"items": [...][...]},[...]]
builton.users.set('5a25250cd57ba213edcba515').getOrders().then(page => {console.log(page.current); // First page});​/*[Order {id: '5c815f19ce39da0008e83eae',total_amount: 42,items: [...][...]},[...]]*/
Path Parameters | Type | Description |
|
| User ID |
Query Parameters | Type | Description |
|
| Number of items to retrieve. |
|
| Which page to retrieve. Default is 10. |
|
| Field used for sorting results. Default is |
|
| Start date, |
|
| End date, |
|
| Date field used to filter results. Default is |
Request --GET /users/5a25250cd57ba213edcba515/payment_methods HTTP/1.1Content-Type: application/jsonAuthorization: Bearer <jwt>X-Builton-Api-Key: <builton-api-key>Host: api.builton.dev
Response --HTTP/1.1 200 OKContent-Type: application/json​[{"_id":{"$oid":"57ee9c43d75d241d82231433"},"active":true,"user":{"$oid":"57ee9c72d76d431f85111432"},"method":"stripe",[...]"card":{[...]}}]
Path Parameters | Type | Description |
|
| User ID |
Query Parameters | Type | Description |
include_deleted |
| If |
size |
| Number of subscriptions per page. Default is 10. |
page |
| Which page to retrieve. Default is 0. |
sort |
| Field used to sort results. Default is |
status |
| The subscription status Default is |
Request --GET /users/5a25250cd57ba213edcba515/subscriptions HTTP/1.1Content-Type: application/jsonAuthorization: Bearer <jwt>X-Builton-Api-Key: <builton-api-key>Host: api.builton.dev
Response --HTTP/1.1 200 OKContent-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": "5a25250cd57ba213edcba515"},"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": "5a25250cd57ba213edcba515"},"trial": false,[...]}]
builton.users.set('5a25250cd57ba213edcba515').getSubscriptions().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,[...]}]*/