User API

1. Querying for Customer Data

URL endpoint: https://stamps.co.id/api/memberships/status

Allowed Method: GET

Require Authentication: Yes

A. Request

You can query for a customer’s data on Stamps .

Parameter	Required	Description
token	Yes	Authentication string
customer	Yes	A string indicating user’s email address to be queried

Example of API call request using cURL

# Please note that for cURL command you need to escape special characters
$ curl 'https://stamps.co.id/api/memberships/status?token=abc&customer=customer@stamps.co.id'

B. Response Data

In response to this API call, Stamps will return response with the following data (in JSON):

Variable	Description
stamps	Total stamps amount the particular user has
membership_status	Membership status of the user
detail	Description of error (if any)
validation_errors	Errors encountered when parsing data (if any)

C. Response Headers

Code	Description
200	Everything worked as expected
400	Bad Request - Often missing a required parameter
401	Unauthorized – Often missing or wrong authentication token
403	Forbidden – You do not have permission for this request
405	HTTP method not allowed - The requested resources cannot be called with the specified HTTP method
500, 502, 503, 504	Server Errors - something is wrong on Stamps’ end

D. Examples

On a successful API call:

HTTP/1.0 200 OK
Vary: Accept
Content-Type: application/json
Allow: POST, OPTIONS
[Redacted Header]

{"stamps": 8917, "membership_status": "Gold"}

API call with missing parameters:

HTTP/1.0 400 BAD REQUEST
Vary: Accept
Content-Type: application/json
Allow: POST, OPTIONS
[Redacted Header]

{"detail": "Your transaction cannot be completed due to the following error(s)", "errors": [{"reward": "This field is required"}]}

If missing or wrong authentication token:

HTTP/1.0 403 FORBIDDEN
Vary: Accept
Content-Type: application/json
Allow: POST, OPTIONS
[Redacted Header]

{"detail": "Authentication credentials were not provided."}

2. Querying for Available Redemptions

URL endpoint: https://stamps.co.id/api/memberships/available-redemptions

Allowed Method: GET

Require Authentication: Yes

A. Request

If you’re planning on building a redemption processing interface into your system, you can use this API to verify which rewards are redeemable for a particular customer.

Parameter	Required	Description
token	Yes	Authentication string
customer	Yes	A string indicating user’s email address to be queried

Example of API call request using cURL:

# Please note that for cURL command you need to escape special characters
$ curl 'https://stamps.co.id/api/memberships/available-redemptions?token=abc&customer=customer@stamps.co.id'

B. Response Data

Stamps responds to this API call with the following data (in JSON):

Variable	Description
rewards	List of rewards available for redemption. Contains id, name, stamps_required, and image_url
vouchers	List of vouchers available for redemption. Contains id, name, quantity, image_url, and expires_on
detail	Description of error (if any)
errors	Errors encountered when parsing data (if any)

C. Response Codes

Code	Description
200	Everything worked as expected
400	Bad Request - Often missing a required parameter
401	Unauthorized – Often missing or wrong authentication token
403	Forbidden – You do not have permission for this request
405	HTTP method not allowed - The requested resources cannot be called with the specified HTTP method
500, 502, 503, 504	Server Errors - something is wrong on Stamps’ end

D. Examples

A successful API call:

HTTP/1.0 200 OK
Vary: Accept
Content-Type: application/json
Allow: POST, OPTIONS
[Redacted Header]

{"rewards": [{"id": 56, "name": "Kopi Tarik", "stamps_required": 50, "image_url": "http://foo.com"}, {"id": 67, "name": "Teh Tarik", "stamps_required": 20, "image_url": "http://foo.com"}], "vouchers": [{"id": 34, "name": "Birthday Promotion", "quantity": 1, "image_url": "http://bar.com", "expires_on": "5-12-2013 23:59"}]}

If transaction is unsuccessful (often missing parameters):

HTTP/1.0 400 BAD REQUEST
Vary: Accept
Content-Type: application/json
Allow: POST, OPTIONS
[Redacted Header]

{"detail": "Your transaction cannot be completed due to the following error(s)", "errors": [{"reward": "This field is required"}]}

3. Querying for User suggestions

URL endpoint: https://stamps.co.id/api/memberships/suggestions

Allowed Method: GET

Require Authentication: Yes

A. Request

If you’re planning on building an autocomplete processing interface into your system, you can use this API to give suggestions.

Parameter	Required	Description
token	Yes	Authentication string
query	Yes	A string indicating query to be processed for the suggestions API

Example of API call request using cURL:

$ curl 'https://stamps.co.id/api/membershipssuggestions?token=abc&query=steve'

B. Response Data

Stamps responds to this API call with the following data (in JSON):

Variable	Description
suggestions	List of suggestions. Contains id, name, stamps, email, and membership

C. Response Codes

Code	Description
200	Everything worked as expected
400	Bad Request - Often missing a required parameter
401	Unauthorized – Often missing or wrong authentication token
403	Forbidden – You do not have permission for this request
405	HTTP method not allowed - The requested resources cannot be called with the specified HTTP method
500, 502, 503, 504	Server Errors - something is wrong on Stamps’ end

D. Examples

A successful API call:

HTTP/1.0 200 OK
Vary: Accept
Content-Type: application/json
Allow: POST, OPTIONS
[Redacted Header]

{
  "suggestions": [
    {
      "membership": "Gold",
      "email": "customer_gold@stamps.co.id",
      "stamps": 100,
      "id": 12,
      "name": "Customer Gold"
    },
    {
      "membership": "Blue",
      "email": "blue_customer@stamps.co.id",
      "stamps": 15,
      "id": 13,
      "name": "Customer Blue"
    }
  ]
}