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.
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:
- 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. - The
X-Fond-Timestamp
provided in the request headers. - The
X-Fond-Nonce
provided in the request headers. - 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",
"sender_id": "d41f57d0-e6e8-4b68-bc36-e3637c498a6d",
"receiver_id": "627f0f32-4e48-408a-93dd-fef3402906a3",
"points": 1234,
"company_id": "b55a7e11-bc16-48ae-a907-007c0695e82e"
}
}
This emits a recognition event when a recognition is received. Here are the payload keys:
Key | Description |
---|---|
sender_type | The recognition creator can be user or company . |
sender_id | id on the sender_type model. |
receiver_id | id of the user receiving the recognition. |
occasion_id | id of the occasion in this recognition. |
points | Integer representing the amount of points given on a recognition. |
company_id | id for the company domain. |
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
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 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
Returns
Status: 200 OK
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" |
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
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.
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
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 - 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 - 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
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 |
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 | "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 |
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 |
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
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",
"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" |
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",
"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" |
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" |
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) |
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 ) |
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
Property | Description | Example |
---|---|---|
id | User id | "5ca999c9-d923-469f-ab23-ab0435cd74c0" |
company_id | Company id the user belongs to | "270d9bc2-8583-4fa7-8770-25a90b81bdbf" |
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" |
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 |
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" |
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" |
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 |
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 - 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 |
---|---|---|---|
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) |
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 ) |
This API doesn't allow you to move a user to another company.
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" |
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" |
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 |
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
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 |