The Builtfirst API draft can be found at https://api-docs.builtfirst.com/
This article is intended for developers trying to use the API to create a redemption.
An API key is needed for each request in this document. Please send requests for a key to support@builtfirst.com.
First
The developer will need to create a buyer user if one doesn't exist.
To very if a user exist execute:
curl --request GET \
--url https://api.builtfirst.com/api/v3/user \
--header 'On-Behalf-Of: [buyer-user-email]' \
--header 'X-API-Key: [api-key]'
To create a new user execute:
curl --request POST \
--url https://api.builtfirst.com/api/v3/user \
--header 'Content-Type: application/json' \
--header 'X-API-Key: [api-key]' \
--data '{"jsonapi":
{
"version":"1.0"
},
"data":{
"type":"token",
"attributes":{
"full_name":"",
"sign_up_organization_name":"",
"email":"",
"first_name":"",
"last_name":""
}
}
}'
Second
The developer will need to obtain the ID of the deal to redeem. This can be done using one of two possible options.
Option 1: Search the deals available in a marketplace for a particular user
Make sure the [api-key] and [buyer-user-email] values are replaced in the CURL below.
curl --request GET \
--url 'https://api.builtfirst.com/api/v3/items?include=deal&sort=recommended&page%5Bsize%5D=5&fields%5Bitem%5D=logo_url%2Cname%2Cslug%2Cdeal%2Cpartner_description%2Cdescription&fields%5Bdeal%5D=average_total_savings_amount%2Caverage_total_savings_prefix%2Cid%2Ctitle' \
--header 'On-Behalf-Of: [buyer-user-email]' \
--header 'X-API-Key: [api-key]' \
--header 'accept: application/json' \
--header 'content-type: application/json'
The call above will return an array of listings, each one may or may not have a deal.
Option 2: If the slug of a particular listing is known the developer can obtain the deal associated to that listing by executing the following command.
Make sure the [slug], [api-key] and [buyer-user-email] values are replaced in the CURL below.
curl --request GET \
--url 'https://api.builtfirst.com/api/v3/items/[slug]?include=deal.redemption%2Clogo&fields%5Bitem%5D=name%2Cdescription%2Cslug%2Clogo%2Cdeal&fields%5Bdeal%5D=title%2Cactivation_type%2Ccontact_email%2Cinstructions%2Crestrictions%2Caverage_total_savings_prefix%2Caverage_total_savings_amount%2Caverage_total_savings_notes%2Cslug%2Cdescription%2Clisting%2Ccategories%2Credemption%2Cnew_customers_only&=' \
--header 'On-Behalf-Of: [buyer-user-email]' \
--header 'X-API-Key: [api-key]' \
--header 'accept: application/json' \
--header 'content-type: application/json'
The call above will return a listing, it may or may not have a deal.
Last
Finally, use the following CURL command to redeem:
Make sure the [api-key] and [buyer-user-email] values are replaced in the CURL below.
curl --request POST \
--url 'https://api-stg.builtfirst.com/api/v3/discounts/1628/redemption?=' \
--header 'On-Behalf-Of: [buyer-user-email]' \
--header 'X-API-Key: [api-key]' \
--header 'accept: application/json' \
--header 'content-type: application/json'
If a deal that is being redeemed was redeemed already, then an error will be returned.
If the redemption type for a deal is a web page the response will have the follwing structure:
{
"data": {
"id": "0000",
"type": "redemption",
"attributes": {
"created_at": "2024-06-06T08:11:31.529-07:00",
"updated_at": "2024-06-06T08:11:31.529-07:00",
"saving_amount": 300.0,
"step": "requested",
"state": "default",
"landing_page_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}
}
}If the redemption type for a deal is an email address the "landing_page_url" attribute in the response above will not be present.