NAV Navbar
Ruby cURL
  • Introduction
  • Authentication
  • Versioning
  • Dates and Times
  • Identifiers
  • Errors
  • Webhooks
  • Companies
  • Corporations
  • Occasions
  • Recognitions
  • SAML
  • Users
  • 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:

    Here are some examples of non-breaking changes:

    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:

    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",
        "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"
    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)
    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"
    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"
    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"
    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"
    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
    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)
    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"
    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"
    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