QuickStart
Create and Verify a New User
You need to create a User identity on the system to interact with most available endpoints. Each User must have a unique, valid email address.
Back to Getting Started with the API
Users get Tokens to Make API Calls
When a new User is created, an email is sent to the User's email address with a link, containing a security token. If the link is clicked on, it tells the system that the email has been received by the correct person, and the User is considered Verified. Verification happens once, but has to be repeated if the email address is changed.
Only a Verified User can log in to obtain a token. The token must be sent with most calls to API endpoints. A token has a lifetime of multiple minutes, and this allows a User to make rapid repeated calls to the API without having to authenticate each call.
Domestic and Business Users
When creating a new User identity, the API endpoint will accept optional fields for Business Users or Organisations. These fields include the Business or Organisation's Legal Name and Address, and details pertaining to the Tax ID.
A Domestic User represents an individual. There is no benefit to marking a Domestic User account as a Business.
A Business User represents a Company or Organisation rather than an Individual. Setting the User account as a Business User account allows the system to use the appropriate business tax treatment when invoices are raised. Business Users can also provide their legal business name, address and Tax ID so that invoices are issued to the correct legal entity and include the relevant tax information. These details can be supplied when the account is created or added later.
Create a New User - Minimal Requirements
The call to create a User requires a name, email and password.
- name (mandatory): 4-128 characters. ASCII Letters, Numbers and Underscore only are permitted. No spaces.
- password (mandatory): 4-128 characters.
- email (mandatory): Must be a valid email address. A verification email will be sent to this address and the account cannot be used until the verification link is clicked.
curl -X POST "https://prod.haggledigital.com/v01/user_create" ^
-H "Content-Type: application/json" ^
-d "{\"name\":\"AshleyAuser\",\"email\":\"ashley@example.com\",\"password\":\"mySuperSecretPassword789\"}"
curl -X POST "https://prod.haggledigital.com/v01/user_create" \
-H "Content-Type: application/json" \
-d '{
"name": "AshleyAuser",
"email": "ashley@example.com",
"password": "mySuperSecretPassword789"
}'
Response
The response will be an HTTP 201 Created message on success, or an error indicating a problem with the supplied data.
Create a New User - Business Fields
The call to create a User requires a name, email and password, and will accept additional optional fields to include the legal Business name and address, and tax code information.
Note that if the tax_id element is supplied, it should also have the tax_id_type. The tax_id_type is a Stripe enumeration, listed here:
https://docs.stripe.com/api/tax_ids/objectFor example, in the United Kingdom a business might have a VAT number, and they would supply this as the tax_id, and use "gb_vat" as the tax_id_type.
curl -X POST "https://prod.haggledigital.com/v01/user_create" ^
-H "Content-Type: application/json" ^
-d "{\"name\":\"AshleyBusiness\",\"email\":\"ashley@workplace.com\",\"password\":\"mySuperSecretPassword789\",\"legal_name\":\"Example Trading Limited\",\"legal_address_free\":\"10 Example Street, London, SW1A 1AA, United Kingdom\",\"legal_address_line1\":\"10 Example Street\",\"legal_address_line2\":\"Westminster\",\"legal_address_city\":\"London\",\"legal_address_region\":\"Greater London\",\"legal_address_zip_postcode\":\"SW1A 1AA\",\"legal_address_iso_country\":\"GB\",\"tax_id\":\"GB123456789\",\"tax_id_type\":\"gb_vat\",\"is_business\":true}"
curl -X POST "https://prod.haggledigital.com/v01/user_create" \
-H "Content-Type: application/json" \
-d '{
"name": "AshleyBusiness",
"email": "ashley@workplace.com",
"password": "mySuperSecretPassword789",
"legal_name": "Example Trading Limited",
"legal_address_free": "10 Example Street, London, SW1A 1AA, United Kingdom",
"legal_address_line1": "10 Example Street",
"legal_address_line2": "Westminster",
"legal_address_city": "London",
"legal_address_region": "Greater London",
"legal_address_zip_postcode": "SW1A 1AA",
"legal_address_iso_country": "GB",
"tax_id": "GB123456789",
"tax_id_type": "gb_vat",
"is_business": true
}'
Response
The response will be an HTTP 201 Created message on success, or an error indicating a problem with the supplied data.
Verification by Email
If the call to create a new User returns an HTTP 201 Created response, a verification email will be sent to the supplied email address.
The email will contain a verification link with an embedded security token. When the link is clicked, the token is returned to the site, and the site then sets the User account as verified for email.
A new User account must go through this validation stage to be used to obtain a token and call other API endpoints.
Ensure that the Spam Folder is checked for new messages. This verification email may be the first email a person receives from the site and therefore might be considered suspicious by some email systems.
API endpoints exist to allow the Email, Legal Address, Tax details and IsBusiness flag to be changed after the User has been created. If the email address is changed, the system will reset the email verification status and send a new verification email.
Getting an Access Token
Once the new User identity has been created and verified, it can be used to get an Access Token. An Access Token is sent with calls to each API endpoint to identify who is making the request.