Beneficiary object

Name Type Notes
id integer Unique identifier of the Beneficiary
first_name string First name of the beneficiary
last_name string Last name of the beneficiary
email string Email of the beneficiary
fixed_contribution float Fixed contribution that the Beneficiary has to pay when trying to redeem any evoucher, regardless of the ticket amount and the redemption amount.
If this is set, percentage_contribution must be null.
percentage_contribution float Percentage contribution that the Beneficiary has to pay when trying to redeem any evoucher (calculated from the ticket amount), regardless of the redemption amount.
If this is set, fixed_contribution must be null.

Read beneficiaries

Read many Beneficiary objects.

You can read a list of your beneficiaries, filtering and sorting them as you please.


POST https://api.gonvert.com/en/v1/beneficiaries/read

Parameters

Name Type Required Notes
start integer Yes The record index from which to start the read operation. Default value is 0.
limit integer Yes The maximum amount of rows to be read. Default value is 25.
sort string No Additional sort property in json format.
You can specify only one sort 'property' among 'first_name', 'last_name', 'email', 'fixed_contribution', 'percentage_contribution'.
The 'direction' must be 'ASC' or 'DESC'.
filter string No Additional filter property in json format.
You can specify multiple filters.
'operator' must be one among 'like' (valid only with strings), 'eq', 'gt', 'lt'.
'property' must be one among 'first_name', 'last_name', 'email', 'fixed_contribution', 'percentage_contribution'

Example request

https://api.gonvert.com/en/v1/beneficiaries/read
start: 0
limit: 2
sort: [{"property":"first_name","direction":"ASC"}]
filter: [{"operator":"like","value":"J","property":"first_name"},{"operator":"like","value":"Smi","property":"last_name"}]

Example successful response

{
    "success": true,
    "total": "2",
    "rows": [
        {
            "id": 55,
            "first_name": "John",
            "last_name": "Smith",
            "email": "john.smith@example.com",
            "percentage_contribution": "10.00",
            "fixed_contribution": null
        },
        {
            "id": 54,
            "first_name": "Jeremy",
            "last_name": "Smith",
            "email": "jeremy.keel@example.com",
            "percentage_contribution": null,
            "fixed_contribution": "5.00"
        }
    ]
}

Write beneficiaries

Use this API to create, update or delete any Beneficiary object.

When creating or updating, keep in mind the following restrictions:

  • You can't specify both fixed and percentage contribution.
  • The fixed contribution must be greater than 0.
  • The percentage contribution must be between 0 and 100.

It is allowed to set both fields to 0 or to not specify either one if you do not want to set up a contribution for that beneficiary.


POST https://api.gonvert.com/en/v1/beneficiaries/write

Parameters

Name Type Required Notes
data string Yes Data used to create/update/delete beneficiaries.
'C' key is used for Create, 'U' key is used for Update, 'D' key is used for Delete.
For every creation the 'id' field must follow a negative numerical progression (-1, -2, -3 ...).
Once created, you cannot edit the email of a Beneficiary.

Example request for create

https://api.gonvert.com/en/v1/beneficiaries/write
data: [{
    "Vouchers.Beneficiary": {
        "C": [{
            "id": -1,
            "first_name": "John",
            "last_name": "Smith",
            "email": "john.smith@examplellbus.com",
            "fixed_contribution": 12.5,
            "percentage_contribution": null
        }]
    }
}]

Example successful response for create

{
"success": true,
"message": "Save completed successfully.",
"data": {
    "Vouchers.Beneficiary": {
        "U": {
            "-1": {
                "id": 68,
                "operator_id": "6",
                "first_name": "John",
                "last_name": "Smith",
                "email": "john.smith@example.com",
                "fixed_contribution": "12.5",
                "percentage_contribution": null
            }
        }
    }
}

Example failed response for create

{
    "success": false,
    "message": "Unique constraint violated. [john.smith@example.com]",
    "errorCode": 2003,
    "identifierValue": "john.smith@example.com"
}

Example request for update

https://api.gonvert.com/en/v1/beneficiaries/write
data: [{
    "Vouchers.Beneficiary": {
        "U": [{
            "id": 68,
            "first_name": "Jeremy"
        }]
    }
}]

Example successful response for update

{
"success": true,
"message": "Save completed successfully.",
"data": {
    "Vouchers.Beneficiary": {
        "U": {
            "68": {
                "id": 68,
                "operator_id": "6",
                "first_name": "Jeremy",
                "last_name": "Smith",
                "email": "john.smith@example.com",
                "fixed_contribution": "12.5",
                "percentage_contribution": null
            }
        }
    }
}

Example failed response for update

{
    "success": false,
    "message": "Oops! It is not possible to edit the email of a beneficiary after creation.",
    "errorCode": 2191,
    "identifierValue": null
}

Example request for delete

https://api.gonvert.com/en/v1/beneficiaries/write
data: [{
    "Vouchers.Beneficiary": {
        "D": [68]
    }
}]

Example successful response for delete

{
"success": true,
"message": "Save completed successfully.",
"data": {
    "Vouchers.Beneficiary": {
        "D": {
            "68": 68
        }
    }
}