Introduction

Welcome to Fond's Provider API documentation. This API is meant to be used by partners, acting as providers, to create and manage companies and users within the Fond platform.

If you wish to become a provider, please reach out to our product team.

Authentication

require 'faraday_middleware'

client = Faraday.new(url: 'https://api.fond.co') do |conn|
  conn.request :json
  conn.response :json, content_type: /\bjson$/
  conn.adapter Faraday.default_adapter
  conn.basic_auth('<API_KEY>', '<API_SECRET>')
end

client.get('/v1/companies/AAAA1234')

$ curl -u "<API_KEY>:<API_SECRET>" https://api.fond.co/v1/companies/AAAA1234

Replace <API_KEY> and <API_SECRET> with your own credentials.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the username value and the API secret as the password value. All API requests must include the Authorization header.

Do not share your API credentials in publicly accessible areas such as GitHub or client-side code.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Versioning

All endpoints are versioned, using vXX tags where XX indicates the version of the endpoint.

The version is specified as a prefix to an endpoint URI. It is possible to use different endpoint versions within the same codebase.

If we need to make breaking changes to an endpoint, we will create a new version of it. We will try to continue supporting older versions as much as possible.

Here are a few examples of what is considered a breaking change and will force us to create a new version of the endpoint:

• Changing an endpoints required parameters
• Removing a property from an endpoint response
• Changing a property's format in an endpoint response

Here are some examples of non-breaking changes:

• Adding an optional parameter to an endpoint
• Adding a property to an endpoint's response

When an endpoint version is no longer supported, the API will return 410 Gone status.

Dates and Times

All date and time properties will be formatted using the ISO 8601 standard.

Identifiers

In most cases our resource identifiers are represented as an UUID such as 1c143f90-6b76-4549-be9c-a755d6170ef9. So when storing them you should allocate 36 character strings.

Errors

API endpoints will use the following response format to return error codes and messages:

{
  "error": {
    "status": 400,
    "message": "A message describing the error."
  }
}

The Fond Provider API uses the following error codes:

Code	Status	Description
400	Bad Request	Your request is invalid.
401	Unauthorized	Your API credentials or token is invalid.
403	Forbidden	You don't have access to the requested resource.
404	Not Found	The specified resource could not be found.
410	Gone	The API endpoint version is no longer supported.
429	Too Many Requests	You're making too many requests. Slow down.
500	Internal Server Error	We had a problem with our server. Try again later.
503	Service Unavailable	We're temporarily offline for maintenance. Please try again later.

Webhooks

A Webhook is an HTTP POST callback. Fond’s API sends different events that may be useful for your application. These events are in JSON format, and you can use them to write logic on your side, send out notifications, generate reports, and more.

Configuring a Webhook

The webhook should be configured by contacting support@fond.co. The event will be sent to the URL that you have provided.

To confirm that you have received a webhook notification, your server must return an HTTP 200 status code. If the call fails, Fond will attempt to post the update again for a period of three days. The time between each retry is given below: 0: 0 days, 0 hours, 0 minutes, 15 seconds 1: 0 days, 0 hours, 0 minutes, 18 seconds 2: 0 days, 0 hours, 1 minutes, 35 seconds 3: 0 days, 0 hours, 9 minutes, 42 seconds 4: 0 days, 0 hours, 38 minutes, 39 seconds 5: 0 days, 1 hours, 54 minutes, 50 seconds 6: 0 days, 4 hours, 41 minutes, 3 seconds 7: 0 days, 10 hours, 0 minutes, 30 seconds 8: 0 days, 19 hours, 20 minutes, 47 seconds 9: 1 days, 10 hours, 37 minutes, 54 seconds Total: 2 days, 23 hours, 25 minutes, 33 seconds

Securing Your Webhook

Once your server is ready to receive payloads, it will listen for any payload sent to the endpoint you have configured. For security reasons, we suggest you limit requests only to those coming from Fond. Fond signs requests with a shared_secret. Your server should validate the request signature using the shared_secret provided by Fond.

Validating the Request

Example:

signature_base = [callback_url, timestamp, nonce, raw_body].join("\n")

comparing_signature = OpenSSL::HMAC.hexdigest(
  OpenSSL::Digest::SHA256.new,
  shared_secret,
  signature_base
)

Rack::Utils.secure_compare(signature, comparing_signature)

The signature hash is passed along the request in a header named X-Fond-Signature.

To validate the signature, compute a hash using the shared secret, a SHA256 digest, and a signature base combining the following parameters:

1. The exact URL string provided to Fond to post updates. It is very important to use the exact URL. Be careful to not add an additional /; otherwise, you won't be able to validate the signature.
2. The X-Fond-Timestamp provided in the request headers.
3. The X-Fond-Nonce provided in the request headers.
4. The request's raw body (JSON string), as it came from the network.

Once you identify those values, you will need to join them into a single string, with each of those values separated by a new line ("\n"). The resulting string will be used as a signature base.

V1 - Recognition Received

Recognition event payload:

{
  "type": "recognition.received",
  "version": "1.0",
  "data": {
    "id": "1d017a9b-b1d8-4d6c-8599-8f5a37a712d8",
    "sender_type": "user",
    "occasion_id": "699dfb62-f4dc-49b1-bb5d-fac10fda00d0",
    "occasion_name": "Great Job",
    "sender_id": "d41f57d0-e6e8-4b68-bc36-e3637c498a6d",
    "sender_name": "John Smith",
    "sender_email": "sender@some.domain.com",
    "receiver_id": "627f0f32-4e48-408a-93dd-fef3402906a3",
    "receiver_name": "Jane Doe",
    "receiver_email": "receiver@some.domain.com",
    "points": 1234,
    "company_id": "b55a7e11-bc16-48ae-a907-007c0695e82e",
    "message": "Thank you for taking care of ...",
    "created_at": "2018-06-25T19:44:09-07:00",
    "share": true
  }
}

This emits a recognition event when a recognition is received. Here are the payload keys:

Key	Description
id	Recognition id
sender_type	The recognition creator can be user or company.
sender_id	id on the sender_type model.
sender_name	Sender's full name (Company name if sender_type is company).
sender_email	Sender's email address (null if sender_type is company).
receiver_id	id of the user receiving the recognition.
receiver_name	Receiver's full name
receiver_email	Receiver's email address
occasion_id	id of the occasion in this recognition.
occasion_name	Name of the recognition
points	Integer representing the amount of points given on a recognition.
company_id	id for the company domain.
message	Message sent (null if share is false)
created_at	Creation date of the recognition
share	Boolean indicating if the recognition is public or private

V1 - Recognition Updated

Recognition event payload:

{
  "type": "recognition.updated",
  "version": "1.0",
  "data": {
    "id": "1d017a9b-b1d8-4d6c-8599-8f5a37a712d8",
    "sender_type": "user",
    "occasion_id": "699dfb62-f4dc-49b1-bb5d-fac10fda00d0",
    "occasion_name": "Great Job",
    "sender_id": "d41f57d0-e6e8-4b68-bc36-e3637c498a6d",
    "sender_name": "John Smith",
    "sender_email": "sender@some.domain.com",
    "receiver_id": "627f0f32-4e48-408a-93dd-fef3402906a3",
    "receiver_name": "Jane Doe",
    "receiver_email": "receiver@some.domain.com",
    "points": 1234,
    "company_id": "b55a7e11-bc16-48ae-a907-007c0695e82e",
    "message": "Thank you for taking care of ...",
    "created_at": "2018-06-25T19:44:09-07:00",
    "share": true
  }
}

This emits a recognition event when a recognition is updated. Here are the payload keys:

Key	Description
id	Recognition id
sender_type	The recognition creator can be user or company.
sender_id	id on the sender_type model.
sender_name	Sender's full name (Company name if sender_type is company).
sender_email	Sender's email address (null if sender_type is company).
receiver_id	id of the user receiving the recognition.
receiver_name	Receiver's full name
receiver_email	Receiver's email address
occasion_id	id of the occasion in this recognition.
occasion_name	Name of the recognition
points	Integer representing the amount of points given on a recognition.
company_id	id for the company domain.
message	Message sent (null if share is false)
created_at	Creation date of the recognition
share	Boolean indicating if the recognition is public or private

V1 - Product Redemption

Product redemption payload:

{
  "type": "redemption.created",
  "version": "1.0",
  "data": {
    "user_id": "d6b5aa51-9810-4082-a8f9-0d1e937722ac",
    "user_email": "example@fond.co",
    "points": 200,
    "cumulative_points_spent": 500,
    "company_id": "e22117bc-8055-4b00-827a-f7dcd6d85e1c"
  }
}

This emits a product redemption event. Here are the data payload keys:

Key	Description
user_id	id for the user that redeemed the product.
user_email	email for the user that redeemed the product.
points	points used for the product redemption.
cumulative_points_spent	cumulative total of points redeemed by the user
company_id	id for the user's company.

Companies

V1 - Create a Company

Create a new company under the authenticated provider.

require 'faraday_middleware'

client = Faraday.new(url: 'https://api.fond.co') do |conn|
  conn.request :json
  conn.response :json, content_type: /\bjson$/
  conn.adapter Faraday.default_adapter
  conn.basic_auth('<API_KEY>', '<API_SECRET>')
end

response = client.post('/v1/companies', {
  domain: 'some.domain.com',
  company_name: 'Some Company, Inc.',
  owner_email: 'admin@some.domain.com',
  owner_name: 'John Smith',
  logo_url: 'https://some.domain.com/logo.png',
})

$ curl -u "<API_KEY>:<API_SECRET>" \
       -d '{"domain":"some.domain.com","company_name":"Some Company, Inc.","owner_email":"admin@some.domain.com","owner_name":"John Smith","logo_url":"https://some.domain.com/logo.png"}' \
       https://api.fond.co/v1/companies/1234

Replace <API_KEY> and <API_SECRET> with your own credentials.

The above code returns a JSON response similar to:

{
  "id": "270d9bc2-8583-4fa7-8770-25a90b81bdbf",
  "domain": "some.domain.com",
  "company_name": "Some Company, Inc.",
  "owner_email": "admin@some.domain.com",
  "owner_name": "John Smith",
  "created_at": "2018-06-25T19:44:09-07:00",
  "updated_at": "2018-06-25T19:44:09-07:00"
}

HTTP Request

POST https://api.fond.co/v1/companies

Parameters

Parameter	Description	Required	Example
domain	Domain name	yes	"some.domain.com"
company_name	Company name	yes	"Some Company, Inc."
owner_email	Administrator email	yes	"admin@some.domain.com"
owner_name	Administrator full name	yes	"John Smith"
logo_url	Company logo URL (320x80)	yes	"https://some.domain.com/logo.png"
corporation_id	Corporation id for this company	no	"6618f752-4c62-4f40-babf-6e29eeb62b13"
points_per_dollar	Points conversion rate	no	50
reserve_alert	Minimum points left in company reserve before notifying company admins	no	25000
reserve_bcc	Additional email to notify when the threshold is broken	no	"csm@some.domain.com"

You can attach a company to a corporation by providing the optional corporation_id parameter you get from creating a corporation.

If you don't provide your own point value using the points_per_dollar parameter, the company will be configured with a default rate of 50 points per dollar.

When the company's reserve wallet drops below the reserve_alert, an email will be sent to all company administrators asking them to add more points to their account. If an email is provided through reserve_bcc, the alert email will also be sent to that email address.

Returns

Status: 201 Created

or

Status: 403 Forbidden if provider is not designated to manage all domain resources

Property	Description	Example
id	Company ID	"270d9bc2-8583-4fa7-8770-25a90b81bdbf"
domain	Domain name	"some.domain.com"
company_name	Company name	"Some Company, Inc."
owner_id	Administrator ID	"3a6dd8ef-4236-4d41-94a6-a51afb0e27f4"
owner_email	Administrator email	"admin@some.domain.com"
owner_name	Administrator full name	"John Smith"
reserve_alert	Minimum points left in company reserve before notifying company admins	25000
reserve_bcc	Additional email to notify when the threshold is broken	"csm@some.domain.com"
created_at	Creation date of the company	"2018-06-25T19:44:09-07:00"
updated_at	Last update of the company	"2018-06-25T19:44:09-07:00"

V1 - List Companies

Retrieve the details of companies owned by the authenticated provider.

require 'faraday_middleware'

client = Faraday.new(url: 'https://api.fond.co') do |conn|
  conn.request :json
  conn.response :json, content_type: /\bjson$/
  conn.adapter Faraday.default_adapter
  conn.basic_auth('<API_KEY>', '<API_SECRET>')
end

response = client.get('/v1/companies')

$ curl -u "<API_KEY>:<API_SECRET>" \
       https://api.fond.co/v1/companies

Replace <API_KEY> and <API_SECRET> with your own credentials.

The above code returns a JSON response similar to:

{
  "page": 1,
  "per_page": 100,
  "total_count": 1,
  "result_count": 1,
  "results": [
    {
      "id": "270d9bc2-8583-4fa7-8770-25a90b81bdbf",
      "domain": "some.domain.com",
      "company_name": "Some Company, Inc.",
      "owner_id": "3a6dd8ef-4236-4d41-94a6-a51afb0e27f4",
      "owner_email": "admin@some.domain.com",
      "owner_name": "John Smith",
      "created_at": "2018-06-25T19:44:09-07:00",
      "updated_at": "2018-06-25T19:44:09-07:00"
    }
  ]
}

HTTP Request

GET https://api.fond.co/v1/companies

Parameters

Parameter	Description	Required	Example
page	Page of companies to retrieve	no	3 (default: 1)
per_page	Companies per page	no	25 (default: 100)
corporation_id	Corporation id for this company	no	"6618f752-4c62-4f40-babf-6e29eeb62b13"

Return a list of company domains associated with the passed corporation_id.

Returns

Status: 200 OK

Property	Description	Example
page	Page of companies retrieved	3
per_page	Companies requested per page	100
total_count	Total number of companies available	150
result_count	Number of companies retrieved on this page	50
results	List of companies	[ /*...*/ ]

The list of results will be the same format as for a single company

V1 - Fetch a Company

Retrieve the details of a company owned by the authenticated provider.

require 'faraday_middleware'

client = Faraday.new(url: 'https://api.fond.co') do |conn|
  conn.request :json
  conn.response :json, content_type: /\bjson$/
  conn.adapter Faraday.default_adapter
  conn.basic_auth('<API_KEY>', '<API_SECRET>')
end

response = client.get('/v1/companies/270d9bc2-8583-4fa7-8770-25a90b81bdbf')

$ curl -u "<API_KEY>:<API_SECRET>" \
       https://api.fond.co/v1/companies/270d9bc2-8583-4fa7-8770-25a90b81bdbf

Replace <API_KEY> and <API_SECRET> with your own credentials.

The above code returns a JSON response similar to:

{
  "id": "270d9bc2-8583-4fa7-8770-25a90b81bdbf",
  "domain": "some.domain.com",
  "company_name": "Some Company, Inc.",
  "owner_id": "3a6dd8ef-4236-4d41-94a6-a51afb0e27f4",
  "owner_email": "admin@some.domain.com",
  "owner_name": "John Smith",
  "created_at": "2018-06-25T19:44:09-07:00",
  "updated_at": "2018-06-25T19:44:09-07:00"
}

HTTP Request

GET https://api.fond.co/v1/companies/:id_or_domain

Returns

Status: 200 OK

Property	Description	Example
id_or_domain	Company ID or Company Domain Name	"270d9bc2-8583-4fa7-8770-25a90b81bdbf" or "yourcompany.com"
domain	Domain name	"some.domain.com"
company_name	Company name	"Some Company, Inc."
owner_id	Administrator ID	"3a6dd8ef-4236-4d41-94a6-a51afb0e27f4"
owner_email	Administrator email	"admin@some.domain.com"
owner_name	Administrator full name	"John Smith"
reserve_alert	Minimum points left in company reserve before notifying company admins	25000
reserve_bcc	Additional email to notify when the threshold is broken	"csm@some.domain.com"
user_count	Total number of active users	1024
points_per_dollar	Points conversion rate	50
created_at	Creation date of the company	"2018-06-25T19:44:09-07:00"
updated_at	Last update of the company	"2018-06-25T19:44:09-07:00"

V1 - Update a Company

Update an existing company under the authenticated provider.

require 'faraday_middleware'

client = Faraday.new(url: 'https://api.fond.co') do |conn|
  conn.request :json
  conn.response :json, content_type: /\bjson$/
  conn.adapter Faraday.default_adapter
  conn.basic_auth('<API_KEY>', '<API_SECRET>')
end

response = client.put('/v1/companies/270d9bc2-8583-4fa7-8770-25a90b81bdbf', {
  company_name: 'New Company, Inc.',
  owner_email: 'admin@new.domain.com',
  owner_name: 'John Smithy',
  logo_url: 'https://some.domain.com/logo-new.png',
})

$ curl -X PUT \
       -u "<API_KEY>:<API_SECRET>" \
       -d '{"company_name":"New Company, Inc.","owner_email":"admin@new.domain.com","owner_name":"John Smithy","logo_url":"https://some.domain.com/logo-new.png"}' \
       https://api.fond.co/v1/companies/270d9bc2-8583-4fa7-8770-25a90b81bdbf

Replace <API_KEY> and <API_SECRET> with your own credentials.

The above code returns a JSON repsonse similar to:

{
  "id": "270d9bc2-8583-4fa7-8770-25a90b81bdbf",
  "domain": "some.domain.com",
  "company_name": "Some Company, Inc.",
  "owner_email": "admin@some.domain.com",
  "owner_name": "John Smith",
  "created_at": "2018-06-25T19:44:09-07:00",
  "updated_at": "2018-06-25T19:44:09-07:00"
}

HTTP Request

PUT https://api.fond.co/v1/companies/:id

Parameters

Parameter	Description	Example
company_name	Company name	"Some Company, Inc."
owner_email	Administrator email	"admin@some.domain.com"
owner_name	Administrator full name	"John Smith"
logo_url	Company logo URL (320x80)	"https://some.domain.com/logo.png"
points_per_dollar	Points conversion rate	50
reserve_alert	Minimum points left in company reserve before notifying company admins	25000
reserve_bcc	Additional email to notify when the threshold is broken	"csm@some.domain.com"

Changing the points value will change the current balance for all users as points are stored in USD cents.

Returns

Status: 200 OK

or

Status: 403 Forbidden if provider is not designated to manage all domain resources

Property	Description	Example
id	Company ID	"270d9bc2-8583-4fa7-8770-25a90b81bdbf"
domain	Domain name	"some.domain.com"
company_name	Company name	"Some Company, Inc."
owner_id	Administrator ID	"3a6dd8ef-4236-4d41-94a6-a51afb0e27f4"
owner_email	Administrator email	"admin@some.domain.com"
owner_name	Administrator full name	"John Smith"
reserve_alert	Minimum points left in company reserve before notifying company admins	25000
reserve_bcc	Additional email to notify when the threshold is broken	"csm@some.domain.com"
created_at	Creation date of the company	"2018-06-25T19:44:09-07:00"
updated_at	Last update of the company	"2018-06-25T19:44:09-07:00"

V1 - Fetch all user's wallets balances for a company

Retrieve the balances (expressed in points) for all users in a specific company.

You can use another endpoint to retrieve the balances for a specific user.

HTTP Request

GET https://api.fond.co/v1/companies/:id/users/balances

Parameters

Parameter	Description	Required	Example
page	User page	no	3 (default: 1)
per_page	Users per page	no	25 (default: 100)

Users can be paginated. There's a hard limit on the number of user balances returned to 100.

Returns

Status: 200 OK

Parameter	Description	Example
id	Company ID	"270d9bc2-8583-4fa7-8770-25a90b81bdbf"
users	List of users and wallets

The list of users and wallets will be the same format as for a single user wallets.

V1 - Fetch all occasions for a company

Retrieve all occasions for a specific company.

require 'faraday_middleware'

client = Faraday.new(url: 'https://api.fond.co') do |conn|
  conn.request :json
  conn.response :json, content_type: /\bjson$/
  conn.adapter Faraday.default_adapter
  conn.basic_auth('<API_KEY>', '<API_SECRET>')
end

response = client.get('/v1/companies/<COMPANY_ID>/occasions')

$ curl -X GET \
       -u "<API_KEY>:<API_SECRET>" \
       -d '{"page":"1","per_page":"10"' \
       https://api.fond.co/v1/companies/<COMPANY_ID>/occasions

Replace <API_KEY> and <API_SECRET> with your own credentials.

Replace <COMPANY_ID> with a company's UUID

You can use another endpoint to retrieve a specific occasion.

HTTP Request

GET https://api.fond.co/v1/companies/:id/occasions

Parameters

Parameter	Description	Required	Example
page	Occasion page	no	3 (default: 1)
per_page	Occasions per page	no	25 (default: 100)

Returns

Status: 200 OK

Property	Description	Example
page	Page of occasions retrieved	3
per_page	Occasions requested per page	100
total_count	Total number of occasions available	150
result_count	Number of occasions retrieved on this page	50
results	List of occasions	[ /*...*/ ]

The list of occasions will be the same format as for a single occasion.

Corporations

Corporations represent a grouping of companies under a common entity.

V1 - Create a Corporation

Create a new corporation under the authenticated provider.

HTTP Request

POST https://api.fond.co/v1/corporations

Parameters

Parameter	Description	Required	Example
name	Corporation name	yes	"My Corporation"

Returns

Status: 201 Created

or

Status: 403 Forbidden if provider is not designated to manage all domain resources

Property	Description	Example
id	Corporation ID	"270d9bc2-8583-4fa7-8770-25a90b81bdbf"
name	Corporation name	"My Corporation"
created_at	Creation date of the corporation	"2018-06-25T19:44:09-07:00"
updated_at	Last update of the corporation	"2018-06-25T19:44:09-07:00"

V1 - List Corporations

Retrieve the details of corporations owned by the authenticated provider.

require 'faraday_middleware'

client = Faraday.new(url: 'https://api.fond.co') do |conn|
  conn.request :json
  conn.response :json, content_type: /\bjson$/
  conn.adapter Faraday.default_adapter
  conn.basic_auth('<API_KEY>', '<API_SECRET>')
end

response = client.get('/v1/corporations')

$ curl -u "<API_KEY>:<API_SECRET>" \
       https://api.fond.co/v1/corporations

Replace <API_KEY> and <API_SECRET> with your own credentials.

The above code returns a JSON response similar to:

{
  "page": 1,
  "per_page": 100,
  "total_count": 1,
  "result_count": 1,
  "results": [
    {
      "id":"270d9bc2-8583-4fa7-8770-25a90b81bdbf",
      "name":"My Corporation",
      "created_at":"2018-06-25T19:44:09-07:00",
      "updated_at":"2018-06-25T19:44:09-07:00"
    }
  ]
}

HTTP Request

GET https://api.fond.co/v1/corporations

Parameters

Parameter	Description	Required	Example
page	Page of corporations to retrieve	no	3 (default: 1)
per_page	Corporations per page	no	25 (default: 100)

Return a list of corporations associated with the authenticated provider.

Returns

Status: 200 OK

Property	Description	Example
page	Page of corporations retrieved	3
per_page	Corporations requested per page	100
total_count	Total number of corporations	150
result_count	Number of corporations retrieved on this page	50
results	List of corporations	[ /*...*/ ]

The list of results will be the same format as for a single corporation

V1 - Fetch a Corporation

Retrieve the details for an existing corporation under the authenticated provider.

HTTP Request

GET https://api.fond.co/v1/corporations/:id

Returns

Status: 200 OK

Property	Description	Example
id	Corporation ID	"270d9bc2-8583-4fa7-8770-25a90b81bdbf"
name	Corporation name	"My Corporation"
created_at	Creation date of the corporation	"2018-06-25T19:44:09-07:00"
updated_at	Last update of the corporation	"2018-06-25T19:44:09-07:00"

V1 - List a Corporation's Companies

Retrieve the details of companies owned by the authenticated provider within a corporation.

HTTP Request

GET https://api.fond.co/v1/corporations/:id/companies

Parameters

Parameter	Description	Required	Example
page	Page of companies to retrieve	no	3 (default: 1)
per_page	Companies per page	no	25 (default: 100)

Returns

Status: 200 OK

Property	Description	Example
page	Page of companies retrieved	3
per_page	Companies requested per page	100
total_count	Total number of companies available	150
result_count	Number of companies retrieved on this page	50
results	List of companies	[ /*...*/ ]

The list of results will be the same format as for a single company

V1 - Update a Corporation

Update an existing corporation under the authenticated provider.

HTTP Request

PUT https://api.fond.co/v1/corporations/:id

Parameters

Parameter	Description	Example
name	Corporation name	"My Corporation"

Returns

Status: 200 OK

or

Status: 403 Forbidden if provider is not designated to manage all domain resources

Property	Description	Example
id	Corporation ID	"270d9bc2-8583-4fa7-8770-25a90b81bdbf"
name	Corporation name	"My Corporation"
created_at	Creation date of the corporation	"2018-06-25T19:44:09-07:00"
updated_at	Last update of the corporation	"2018-06-25T19:44:09-07:00"

Occasions

V1 - Create an Occasion

Create a new recognition occasion for a company.

HTTP Request

POST https://api.fond.co/v1/occasions

Parameters

Parameter	Description	Required	Example
company_id	Company id the user belongs to	yes	"270d9bc2-8583-4fa7-8770-25a90b81bdbf"
name	Name of the occasion	yes	"Great Job"
title	Email title for the occasion	yes	"You Did a Great Job!"
default_message	Default message used for recognitions that don't specify a message	yes	"Thank you for helping our company succeed!"
enabled	Boolean to allow this occasion to be used for recognitions	no	false (default: true)
visible	Controls whether the occasion can be managed in the company admin tool or selected in the recognition form	no	false (default: true)

Returns

Status: 201 Created

Property	Description	Example
id	Occasion id	"6618f752-4c62-4f40-babf-6e29eeb62b13"
company_id	Company id the occasion belongs to	"270d9bc2-8583-4fa7-8770-25a90b81bdbf"
name	Name of the occasion	"Great Job"
title	Email title for the occasion	"You Did a Great Job!"
default_message	Default message used for recognitions that don't specify a message	"Thank you for helping our company succeed!"
enabled	Boolean to allow this occasion to be used for recognitions	false
visible	Controls whether the occasion can be managed in the company admin tool or selected in the recognition form	false
global	Whether this occasion is global or not, all occasions created via the API are not global, they are company specific by default	false
created_at	Creation date of the occasion	"2018-06-25T19:44:09-07:00"
updated_at	Last update of the occasion	"2018-06-25T19:44:09-07:00"

V1 - Fetch an Occasion

Retrieve an existing occasion details for a company.

HTTP Request

GET https://api.fond.co/v1/occasions/:id

Returns

Status: 200 OK

Property	Description	Example
id	Occasion id	"e70c1df4-e0f7-4ac7-a056-07754e57a679"
company_id	Company id the occasion belongs to (null if global is true)	"270d9bc2-8583-4fa7-8770-25a90b81bdbf"
name	Name of the recognition	"Great Job"
title	Email title for the recognition	"You Did a Great Job!"
default_message	Default message used for recognitions that don't specify a message	"Thank you for helping our company succeed!"
enabled	Boolean to allow this occasion to be used for recognitions	false
visible	Controls whether the occasion can be managed in the company admin tool or selected in the recognition form	false
global	Whether this occasion is global or not, all occasions created via the API are not global, they are company specific by default	false
created_at	Creation date of the occasion	"2018-06-25T19:44:09-07:00"
updated_at	Last update of the occasion	"2018-06-25T19:44:09-07:00"

V1 - Update an Occasion

Update an existing occasion for a company.

HTTP Request

PUT https://api.fond.co/v1/occasions/:id

Parameters

Parameter	Description	Required	Example
name	Name of the recognition	no	"Great Job"
title	Email title for the recognition	no	"You Did a Great Job!"
default_message	Default message used for recognitions that don't specify a message	no	"Thank you for helping our company succeed!"
enabled	Boolean to allow this occasion to be used for recognitions	no	false
visible	Controls whether the occasion can be managed in the company admin tool or selected in the recognition form	no	false

Returns

Status: 200 OK

Property	Description	Example
id	Occasion id	"e70c1df4-e0f7-4ac7-a056-07754e57a679"
company_id	Company id the occasion belongs to	"270d9bc2-8583-4fa7-8770-25a90b81bdbf"
name	Name of the recognition	"Great Job"
title	Email title for the recognition	"You Did a Great Job!"
default_message	Default message used for recognitions that don't specify a message	"Thank you for helping our company succeed!"
enabled	Boolean to allow this occasion to be used for recognitions	false
visible	Controls whether the occasion can be managed in the company admin tool or selected in the recognition form	false
global	Whether this occasion is global or not, all occasions created via the API are not global, they are company specific by default	false
created_at	Creation date of the occasion	"2018-06-25T19:44:09-07:00"
updated_at	Last update of the occasion	"2018-06-25T19:44:09-07:00"

V1 - Delete an Occasion

Delete an existing occasion for a company.

HTTP Request

DELETE https://api.fond.co/v1/occasions/:id

Returns

Status: 204 No Content

Recognitions

V1 - Create a Recognition

Sends a recognition to one or more users.

HTTP Request

POST https://api.fond.co/v1/recognitions

Parameters

Parameter	Description	Required	Example
occasion_id	Occasion id	yes	"e70c1df4-e0f7-4ac7-a056-07754e57a679"
sender_type	Either user or company	yes	"user"
sender_id	User id sending the recognition	yes	"14bd0549-e865-419e-8360-c97cc4b1939c"
receiver_ids	List of user ids being recognized	yes	"3d443091-aea5-46e7-abc2-493486a2b0ac,bcf02a0e-9019-4adb-9638-88a48d80bc35"
points_per_receiver	Number of points to give to each receiver	yes	100
message	Message to send to each receiver	no	"Thank you for taking care of ..."
share	Boolean indicating if the recognition is public or private	no	false (default: true)

When sending a recognition to multiple users, the sender's wallet will need to have points_per_receiver * number of receivers points available. If the sender's wallet has insufficient funds, none of the recognitions will be sent. For example, if a recognition is sent to 5 users, with a points_per_recognition set to 50 points, the sender's wallet needs to have at least 250 points available for the recognitions to go through.

If the message isn't provided, the occasion's default_message will be used.

Returns

Status: 201 Created

The response will contain a list of recognition objects for each receiver. Below are the attributes for a single recognition object.

Property	Description	Example
id	Recognition id	"6618f752-4c62-4f40-babf-6e29eeb62b13"
receiver_id	User id who received the recognition	"3a6dd8ef-4236-4d41-94a6-a51afb0e27f4"
sender_type	Either user or company	"user"
sender_id	Sender id who sent the recognition, related to sender_type	"14bd0549-e865-419e-8360-c97cc4b1939c"
message	Message sent	"Thank you for taking care of ..."
points	Points sent	100
share	Boolean indicating if the recognition is public or private	true
occasion_id	Occasion id	"e70c1df4-e0f7-4ac7-a056-07754e57a679"
created_at	Creation date of the recognition	"2018-06-25T19:44:09-07:00"

Errors

Code	Message	Description
400	"Insufficient funds"	The sender does not have sufficient funds to send the recognitions
400	"Invalid points_per_receiver, value must be between A and B"	The points_per_receiver value is invalid. The value needs to be within a specific range. A and B are dynamic values expressed as integers. The lower bound A will either be 0 or 1 depending on which options are enabled on the company. The upper bound B represents our hard limit expressed using the point conversion rate for your company. We have a hard limit of $5,000 per recognition.`

SAML

<saml2:Conditions ... >
    <saml2:AudienceRestriction>
        <saml2:Audience>https://fond.co/saml/your_domain</saml2:Audience>
    </saml2:AudienceRestriction>
</saml2:Conditions>

Configuring companies with SAML allows users to log into Fond with the click of a button. The three pieces of information we need for the integration are the idP entity ID, SSO URL, and certificate. Upon creation, we generate and return an sp_id (also known as SP entity ID, or audience) and will be of the form https://fond.co/saml/your_domain, where your_domain is the domain of your company. This sp_id or audience must be present in the saml2:Conditions tag within your SAML assertions, as shown to the right.

V1 - Update SAML Configuration

Update SAML configuration for a company.

require 'faraday_middleware'

client = Faraday.new(url: 'https://api.fond.co') do |conn|
  conn.request :json
  conn.response :json, content_type: /\bjson$/
  conn.adapter Faraday.default_adapter
  conn.basic_auth('<API_KEY>', '<API_SECRET>')
end

response = client.put('/v1/companies/6618f752-4c62-4f40-babf-6e29eeb62b13/saml', {
  idp_id: 'https://idp.provider.com/some-unique-identifier',
  idp_url: 'https://some.domain.com/saml/sso',
  idp_certificate: File.read('/path/to/certificate'),
  active: true,
})

$ curl -X PUT \
       -u "<API_KEY>:<API_SECRET>" \
       -d '{"idp_id":"https://idp.provider.com/some-unique-identifier","idp_url":"https://some.domain.com/saml/sso","idp_certificate":"-----BEGIN CERTIFICATE-----.....","active":"true"}' \
       https://api.fond.co/v1/companies/AAAA1234/saml

Replace <API_KEY> and <API_SECRET> with your own credentials.

The above code returns a JSON response similar to:

{
  "idp_id": "your_idp_id",
  "idp_url": "http://localhost:3456/your_idp_url",
  "sp_id": "https://fond.co/saml/your_domain",
  "active": true
}

HTTP Request

PUT https://api.fond.co/v1/companies/:id/saml

Parameters

Parameter	Description	Example
idp_id	IDP Entity identifier	"https://idp.provider.com/some-unique-identifier"
idp_url	IDP SSO Target URL	"https://some.domain.com/saml/sso"
idp_certificate	IDP Certificate	"-----BEGIN CERTIFICATE-----....."
active	Is SAML active	true (Default: false)

Supported active values:

Value	Description
true	Enable SAML configuration
false	Disable SAML configuration

Returns

Status: 200 OK

Property	Description	Example
idp_id	Updated company's idP ID	"your_idp_id"
idp_url	Updated company's idP URL	"http://localhost:3456/your_idp_url"
sp_id	Company's assigned SP ID	"https://fond.co/saml/your_domain"
active	Is SAML active	true

V1 - Fetch SAML Configuration

Retrieve the SAML configuration for a company.

require 'faraday_middleware'

client = Faraday.new(url: 'https://api.fond.co') do |conn|
  conn.request :json
  conn.response :json, content_type: /\bjson$/
  conn.adapter Faraday.default_adapter
  conn.basic_auth('<API_KEY>', '<API_SECRET>')
end

response = client.get('/v1/companies/6618f752-4c62-4f40-babf-6e29eeb62b13/saml')

$ curl -u "<API_KEY>:<API_SECRET>" \
       https://api.fond.co/v1/companies/6618f752-4c62-4f40-babf-6e29eeb62b13/saml

Replace <API_KEY> and <API_SECRET> with your own credentials.

The above code returns a JSON response similar to:

{
  "idp_id": "your_idp_id",
  "idp_url": "http://localhost:3456/your_idp_url",
  "sp_id": "https://fond.co/saml/your_domain",
  "active": true
}

HTTP Request

GET https://api.fond.co/v1/companies/:id/saml

Returns

Status: 200 OK

Property	Description	Example
idp_id	Company's idP ID	"your_idp_id"
idp_url	Company's idP URL	"http://localhost:3456/your_idp_url"
sp_id	Update company's SP ID	"https://fond.co/saml/your_domain"
active	Is SAML active	true

Supported active values:

Value	Description
true	SAML configuration enabled
false	SAML configuration disabled

Users

V1 - Create a User

Create a new user for a company.

HTTP Request

POST https://api.fond.co/v1/users

Parameters

Parameter	Description	Required	Example
company_id	Company id the user belongs to	yes	"270d9bc2-8583-4fa7-8770-25a90b81bdbf"
email	User's email address	yes	"user@some.domain.com"
first_name	User's first name	yes	"John"
last_name	User's last name	yes	"Smith"
department	User's department	no	"Engineering"
title	User's profession title	no	"Senior Software Engineer"
employee_id	User's employee id	no	"EEE10123"
birthday	Birth day and month (mm/dd)	no	"05/01" (May 1st)
country_code	Employee's country (alpha-2 or alpha-3 ISO 3166 country code)	no	"US"
work_start_date	Date employee joined the company (mm/dd/yyyy)	no	"04/01/2014" (April 1st 2014)
office_city	Employee's office city	no	"San Francisco"
office_state	Employee's office state	no	"California"
office_country	Employee's office country	no	"USA"
company_admin	Boolean indicating if user is a company administrator	no	true (default: false)
corporation_admin	Boolean indicating if user is a corporation administrator	no	true (default: false)
groups	Employee's groups	no	"group1,group2"

If the corporation_admin flag is provided and set to true, but the company is not part of a corporation, the flag will be ignored.

Returns

Status: 201 Created

or

Status: 403 Forbidden if provider is not designated to manage all domain resources

Property	Description	Example
id	User id	"5ca999c9-d923-469f-ab23-ab0435cd74c0"
company_id	Company id the user belongs to	"270d9bc2-8583-4fa7-8770-25a90b81bdbf"
email	User's email address	"user@some.domain.com"
first_name	User's first name	"John"
last_name	User's last name	"Smith"
department	User's department	"Engineering"
title	User's profession title	"Senior Software Engineer"
employee_id	User's employee id	"EEE10123"
birthday	Birth day and month (mm/dd)	"05/01"
country_code	Employee's country	"US"
work_start_date	Date employee joined the company (mm/dd/yyyy)	"04/01/2014"
office_city	Employee's office city	"San Francisco"
office_state	Employee's office state	"California"
office_country	Employee's office country	"USA"
company_admin	Boolean indicating if user is a company administrator	false
corporation_admin	Boolean indicating if user is a corporation administrator	false
groups	Employee's groups	"group1,group2"
created_at	Creation date of the user	"2018-06-25T19:44:09-07:00"
updated_at	Last update of the user	"2018-06-25T19:44:09-07:00"

V1 - Fetch a User

Retrieve a user's details from a company.

HTTP Request

GET https://api.fond.co/v1/users/:id

Returns

Status: 200 OK

Property	Description	Example
id	User id	"e70c1df4-e0f7-4ac7-a056-07754e57a679"
company_id	Company id the user belongs to	"270d9bc2-8583-4fa7-8770-25a90b81bdbf"
email	User's email address	"user@some.domain.com"
first_name	User's first name	"John"
last_name	User's last name	"Smith"
department	User's department	"Engineering"
title	User's profession title	"Senior Software Engineer"
employee_id	User's employee id	"EEE10123"
birthday	Birth day and month (mm/dd)	"05/01"
country_code	Employee's country	"US"
work_start_date	Date employee joined the company (mm/dd/yyyy)	"04/01/2014"
office_city	Employee's office city	"San Francisco"
office_state	Employee's office state	"California"
office_country	Employee's office country	"USA"
company_admin	Boolean indicating if user is a company administrator	false
corporation_admin	Boolean indicating if user is a corporation administrator	false
groups	Employee's groups	"in-house"
created_at	Creation date of the user	"2018-06-25T19:44:09-07:00"
updated_at	Last update of the user	"2019-07-26T19:44:09-07:00"
deleted_at	Deletion date of the user	"2019-07-26T19:44:09-07:00"

V1 - Fetch Recognitions Received by a User

Retrieve recognitions received by a user.

HTTP Request

GET https://api.fond.co/v1/users/:id/recognitions_received

Returns

Status: 200 OK

Property	Description	Example
page	Page of recognitions retrieved	3
per_page	Recognitions requested per page	100
total_count	Total number of recognitions	150
result_count	Number of recognitions retrieved on this page	50
results	List of recognitions	[ /*...*/ ]

The list of results will be the same format as for a single recognition

V1 - Fetch Recognitions Sent by a User

Retrieve recognitions sent by a user.

HTTP Request

GET https://api.fond.co/v1/users/:id/recognitions_sent

Returns

Status: 200 OK

Property	Description	Example
page	Page of recognitions retrieved	3
per_page	Recognitions requested per page	100
total_count	Total number of recognitions	150
result_count	Number of recognitions retrieved on this page	50
results	List of recognitions	[ /*...*/ ]

The list of results will be the same format as for a single recognition

V1 - Update a User

Update an existing user for a company.

HTTP Request

PUT https://api.fond.co/v1/users/:id

Parameters

Parameter	Description	Required	Example
email	User's email address	no	"user@some.domain.com"
first_name	User's first name	no	"John"
last_name	User's last name	no	"Smith"
department	User's department	no	"Engineering"
title	User's profession title	no	"Senior Software Engineer"
employee_id	User's employee id	no	"EEE10123"
birthday	Birth day and month (mm/dd)	no	"05/01" (May 1st)
country_code	Employee's country (alpha-2 or alpha-3 ISO 3166 country code)	no	"US"
work_start_date	Date employee joined the company (mm/dd/yyyy)	no	"04/01/2014" (April 1st 2014)
office_city	Employee's office city	no	"San Francisco"
office_state	Employee's office state	no	"California"
office_country	Employee's office country	no	"USA"
company_admin	Boolean indicating if user is a company administrator	no	true (default: false)
corporation_admin	Boolean indicating if user is a corporation administrator	no	true (default: false)
groups	Employee's groups	no	"group1,group2"
active	Allows reactivating a user	no	true

Note: This API doesn't allow you to delete a user or move a user to another company.

Returns

Status: 200 OK

or

Status: 403 Forbidden if provider is not designated to manage all domain resources

or

Status: 404 Not Found if unable to find a user account OR reactivate a deactivated user

Property	Description	Example
id	User id	"e70c1df4-e0f7-4ac7-a056-07754e57a679"
company_id	Company id the user belongs to	"270d9bc2-8583-4fa7-8770-25a90b81bdbf"
email	User's email address	"user@some.domain.com"
first_name	User's first name	"John"
last_name	User's last name	"Smith"
department	User's department	"Engineering"
title	User's profession title	"Senior Software Engineer"
employee_id	User's employee id	"EEE10123"
birthday	Birth day and month (mm/dd)	"05/01"
country_code	Employee's country	no
work_start_date	Date employee joined the company (mm/dd/yyyy)	"04/01/2014"
office_city	Employee's office city	"San Francisco"
office_state	Employee's office state	"California"
office_country	Employee's office country	"USA"
company_admin	Boolean indicating if user is a company administrator	false
corporation_admin	Boolean indicating if user is a corporation administrator	false
groups	Employee's groups	no
created_at	Creation date of the user	"2018-06-25T19:44:09-07:00"
updated_at	Last update of the user	"2018-06-25T19:44:09-07:00"

V1 - Delete a User

Delete a user from a company.

HTTP Request

DELETE https://api.fond.co/v1/users/:id

Returns

Status: 204 No Content

or

Status: 403 Forbidden if provider is not designated to manage all domain resources

V1 - Search Users

Retrieve the details of users belonging to the authenticated provider.

require 'faraday_middleware'

client = Faraday.new(url: 'https://api.fond.co') do |conn|
  conn.request :json
  conn.response :json, content_type: /\bjson$/
  conn.adapter Faraday.default_adapter
  conn.basic_auth('<API_KEY>', '<API_SECRET>')
end

response = client.post('/v1/users/search', { email: "user@some.domain.com" })

$ curl -u "<API_KEY>:<API_SECRET>" \
       https://api.fond.co/v1/users/search

Replace <API_KEY> and <API_SECRET> with your own credentials.

The above code returns a JSON response similar to:

{
  "page": 1,
  "per_page": 100,
  "total_count": 1,
  "result_count": 1,
  "results": [
    {
      "id": "e70c1df4-e0f7-4ac7-a056-07754e57a679",
      "company_id": "270d9bc2-8583-4fa7-8770-25a90b81bdbf",
      "email": "user@some.domain.com",
      "first_name": "John",
      "last_name": "Smith",
      "department": "Engineering",
      "title": "Senior Software Engineer",
      "employee_id": "EEE10123",
      "birthday": "05/01",
      "work_start_date": "04/01/2014",
      "office_city": "San Francisco",
      "office_state": "California",
      "office_country": "USA",
      "company_admin": false,
      "corporation_admin": false,
      "created_at": "2018-06-25T19:44:09-07:00",
      "updated_at": "2019-07-26T19:44:09-07:00",
      "deleted_at": "2019-07-26T19:44:09-07:00"
    }
  ]
}

HTTP Request

POST https://api.fond.co/v1/users/search

Parameters

Parameter	Description	Required	Example
email	Email of the user to search for (use '%' for wildcard matching)	no	"%@some.domain.com"
page	Page of corporations to retrieve	no	3 (default: 1)
per_page	Corporations per page	no	25 (default: 100)

Return a list of users associated with the authenticated provider that match the search params.

Returns

Status: 200 OK

Property	Description	Example
page	Page of users retrieved	3
per_page	Users requested per page	100
total_count	Total number of users	150
result_count	Number of users retrieved on this page	50
results	List of users	[ /*...*/ ]

The list of results will be the same format as for a single user

V1 - Fetch wallets balance for a specific user

Retrieve the balance (expressed in points) for all the wallets for a specific user.

HTTP Request

GET https://api.fond.co/v1/users/:id/balances

Returns

Status: 200 OK

Not every user will have all the wallets, you need to verify the user has a specific wallet before trying to use it.

Property	Description	Example
id	User id	"3a6dd8ef-4236-4d41-94a6-a51afb0e27f4"
wallets	List of wallet objects

Each wallet object will have the following attributes:

Property	Description	Example
type	Type of wallet (user_wallet, peer_wallet or manager_wallet)	"user_wallet"
points	Points in the wallet	50
cumulative_points_spent	Cumulative total for points transfered out of this wallet	200

Here's a description of possible wallets:

Type	Description
user_wallet	Contains the points that a user has earned and that they can spend on rewards
peer_wallet	Contains the points that can be used to send recognitions to other users
manager_wallet	Contains the points that a manager can use to send recognitions to other users

V1 - Fetch transactions for a User

Retrieve transactions for a specific user.

HTTP Request

GET https://api.fond.co/v1/users/:id/transactions

Parameters

Parameter	Description	Required	Example
type	Wallet type	yes	"user_wallet"
page	Transaction page	no	3
per_page	Transactions per page	no	25 (default: 100)

For the different wallet types, you should retrieve the user balances first to see which wallets are available.

Transactions can be paginated. There's a hard limit on the number of transactions returned to 100.

Returns

Status: 200 OK

Property	Description	Example
id	User id	"e70c1df4-e0f7-4ac7-a056-07754e57a679"
type	Wallet type	"user_wallet"
transactions	List of transactions

See a description of the different user wallet types here.

Each transaction will contain the following attributes:

Property	Description	Example
type	Transaction type (debit or credit)	"debit"
points	Transaction amount	50
reason	The reason for the transactions (recognition, redemption, ...)	"recognition"
created_at	Date and time of the transaction	"2018-06-25T19:44:09-07:00"

Transaction Reasons:

Name	Description
recognition	The user received (user_wallet) or gave (peer_wallet / manager_wallet) points via recognitions
redemption	The user redeemed a reward using points
point distribution	The user was given points via a scheduled distribution
user deleted	The user was deactivated, returning wallet funds to the Company Reserve
refund	A user returned a reward, or a reward redemption failed, returning the points spent to the user's wallet
override	The funds in a wallet were replaced with a different amount