Theme switcher

API Reference

Theneo is the quickest, simplest way to generate high-quality, interactive API docs. Just import your API collection and we'll take care of the rest.

⚠️ Note: All of the stated endpoints and sections are for demonstration purposes only. Theneo does not manage payments API. Get sales data, itemize payments, push orders to POS, and more.The Orders API provides a one-stop shop for integrating advanced payment functionality. You can itemize payments with custom line items or catalog objects, send orders to real Point of Sale devices to be fulfilled, and more.In addition, the Orders API allows you to look through all of a seller's previous sales and returns itemization data, customer references, and other information from POS or online transactions.

Was this section helpful?

What made this section unhelpful for you?

Base URL

Production:

https://app.theneo.io

Language Box

Status Codes

200

Everything worked as expected.

400

The request was unacceptable, often due to missing a required parameter.

401

The request was unacceptable, often due to missing a required parameter.

402

The parameters were valid but the request failed.

403

The API key doesnt have permissions to perform the request.

404

The requested resource does not exist.

Error Codes

api_connection_error

Failure to connect to API.

api_error

API errors cover any other type of problem (e.g., a temporary problem with servers), and are extremely uncommon.

authentication_error

Failure to properly authenticate yourself in the request.

card_error

Card errors are the most common type of error you should expect to handle. They result when the user enters a card that can't be charged for some reason.

idempotency_error

Idempotency errors occur when an Idempotency-Key is re-used on a request that does not match the first request's API endpoint and parameters.

invalid_request_error

Invalid request errors arise when your request has invalid parameters.

rate_limit_error

Too many requests hit the API too quickly.

validation_error

Errors triggered by our client-side libraries when failing to validate fields (e.g., when a card number or expiration date is invalid or incomplete).

Was this section helpful?

What made this section unhelpful for you?

Customer CRM API Example

🚀 Theneo is the quickest, simplest way to generate high-quality, interactive API docs. Just import your API collection and we'll take care of the rest.

Please Note this is just a demo document, none of the endpoints here are real

Was this section helpful?

What made this section unhelpful for you?

Endpoints

POST
PUT
GET
POST
DELETE
Was this section helpful?

What made this section unhelpful for you?

Create customer

Creates a new customer for a business.

You must provide at least one of the following values in your request to this endpoint:

Body Parameters

given_namestring

Name of the customer

last_namestring

The customer last name

email_addressstring

The email address of the customer

addressobject

The address of the customer

Show child attributes

phone_numberstring

Phone number of the customer

reference_idstring

The reference ID for the customer

notestring

Note for the customer

Response

200
Object

Response Attributes

customerobject

Show child attributes

400
Object

Response Attributes

errorsarray

Show child attributes

400
Object

Response Attributes

errorsarray

Show child attributes

Was this section helpful?

What made this section unhelpful for you?

POST

/v2/customers

Select
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 curl --location 'https://app.theneo.io/v2/customers' \ --data-raw '{ "given_name": "Theneo", "last_name": "APIDoc", "email_address": "hello@etheneo.io", "address": { "maling_address": { "address_line_1": "500 Yale Avenue", "address_line_2": "WeWork" }, "locality": "Seattle", "administrative_district_level_1": "WA", "postal_code": "98109", "country": "US" }, "phone_number": "1-212-123-4567", "reference_id": "YOUR_REFERENCE_ID", "note": "Amazing API Docs" }'

Response

{
  "customer": {
    "id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
    "created_at": "2016-03-23T20:21:54.859Z",
    "updated_at": "2016-03-23T20:21:54.859Z",
    "given_name": "Theneo",
    "family_name": "APIDoc",
    "email_address": "hello@etheneo.io",
    "address": {
      "maling_address": {
        "address_line_1": "500 Yale Avenue",
        "address_line_2": "WeWork"
      },
      "locality": "Seattle",
      "administrative_district_level_1": "WA",
      "postal_code": "98109",
      "country": "US"
    },
    "phone_number": "1-212-123-4567",
    "reference_id": "YOUR_REFERENCE_ID",
    "note": "Amazing API Docs",
    "preferences": {
      "email_unsubscribed": false
    },
    "creation_source": "THIRD_PARTY",
    "version": 0
  }
}
Was this section helpful?

What made this section unhelpful for you?

Update customer

Updates a customer profile.

To change an attribute, specify the new value. To remove an attribute, specify the value as an empty string or empty object.

As a best practice, you should include the version field in the request to enable optimistic concurrency control. The value must be set to the current version of the customer profile.

To update a customer profile that was created by merging existing profiles, you must use the ID of the newly created profile.

Header Parameters

Authorizationstring
Content-Typestring

Path Parameters

customer_idstring Required

Body Parameters

phone_numberstring
email_addressstring
notestring
versionnumber

Response

200
Object

Response Attributes

customerobject

Show child attributes

200
Object
Was this section helpful?

What made this section unhelpful for you?

PUT

/v2/customers/{customer_id}

Select
1 2 3 4 5 6 7 8 9 curl --location --globoff --request PUT 'https://app.theneo.io/v2/customers/{customer_id}' \ --header 'Authorization: Bearer ACCESS_TOKEN' \ --header 'Content-Type: application/json' \ --data-raw '{ "phone_number": "", "email_address": "New.hello@theneo.io", "note": "updated customer note", "version": 2 }'

Response

{
  "customer": {
    "id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
    "created_at": "2016-03-23T20:21:54.859Z",
    "updated_at": "2016-05-15T20:21:55Z",
    "given_name": "Theneo",
    "family_name": "APIDoc",
    "email_address": "hello@etheneo.io",
    "address": {
      "maling_address": {
        "address_line_1": "500 Yale Avenue",
        "address_line_2": "WeWork"
      },
      "locality": "Seattle",
      "administrative_district_level_1": "WA",
      "postal_code": "98109",
      "country": "US"
    },
    "phone_number": "1-212-123-4567",
    "reference_id": "YOUR_REFERENCE_ID",
    "note": "updated customer note",
    "preferences": {
      "email_unsubscribed": false
    },
    "creation_source": "THIRD_PARTY",
    "version": 3
  }
}
Was this section helpful?

What made this section unhelpful for you?

Retrieve customer

Returns details for a single customer.

Header Parameters

Authorizationstring
Content-Typestring

Path Parameters

customer_idstring Required

Response

200
Object

Response Attributes

customerobject

Show child attributes

200
Object
Was this section helpful?

What made this section unhelpful for you?

GET

/v2/customers/{customer_id}

Select
1 2 3 curl --location --globoff 'https://app.theneo.io/v2/customers/{customer_id}' \ --header 'Authorization: Bearer ACCESS_TOKEN' \ --header 'Content-Type: application/json'

Response

{
  "customer": {
    "id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
    "created_at": "2016-03-23T20:21:54.859Z",
    "updated_at": "2016-05-15T20:21:55Z",
    "given_name": "Theneo",
    "family_name": "APIDoc",
    "email_address": "hello@etheneo.io",
    "address": {
      "maling_address": {
        "address_line_1": "500 Yale Avenue",
        "address_line_2": "WeWork"
      },
      "locality": "Seattle",
      "administrative_district_level_1": "WA",
      "postal_code": "98109",
      "country": "US"
    },
    "phone_number": "1-212-123-4567",
    "reference_id": "YOUR_REFERENCE_ID",
    "note": "updated customer note",
    "preferences": {
      "email_unsubscribed": false
    },
    "creation_source": "THIRD_PARTY",
    "version": 3
  }
}
Was this section helpful?

What made this section unhelpful for you?

Search customers

Utilizes one or more supported query filters to search the associated customer profiles with a Theneo account.
Without an explicit query filter, SearchCustomers returns all customer profiles based on given name and family name in alphabetical order.
Under normal working conditions, newly created or modified customer profiles become available for the search operation in significantly less than 30 seconds. Occasionally, propagation of new or updated profiles can take up to a minute or longer, particularly during network outages and events.

Header Parameters

Authorizationstring
Content-Typestring

Body Parameters

queryobject

Show child attributes

limitnumber

Response

200
Object

Response Attributes

customersarray

Show child attributes

cursorstring
Was this section helpful?

What made this section unhelpful for you?

POST

/v2/customers/search

Select
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 curl --location 'https://app.theneo.io/v2/customers/search' \ --header 'Authorization: Bearer ACCESS_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "query": { "filter": { "email_address": { "fuzzy": "example.com" }, "creation_source": { "values": [ "THIRD_PARTY" ], "rule": "INCLUDE" }, "created_at": { "start_at": "2018-01-01T00:00:00-00:00", "end_at": "2018-02-01T00:00:00-00:00" }, "group_ids": { "all": [ "545AXB44B4XXWMVQ4W8SBT3HHF" ] } }, "sort": { "field": "CREATED_AT", "order": "ASC" } }, "limit": 2 }'

Response

{
  "customers": [
    {
      "id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
      "created_at": "2018-01-23T20:21:54.859Z",
      "updated_at": "2020-04-20T10:02:43.083Z",
      "given_name": "James",
      "family_name": "Bond",
      "email_address": "james.bond@example.com",
      "address": {
        "address_line_1": "500 Yale Ave N",
        "address_line_2": "WeWork",
        "locality": "Seattle",
        "administrative_district_level_1": "WA",
        "postal_code": "10003",
        "country": "US"
      },
      "phone_number": "1-212-555-4250",
      "reference_id": "YOUR_REFERENCE_ID_2",
      "preferences": {
        "email_unsubscribed": false
      },
      "creation_source": "DIRECTORY",
      "group_ids": [
        "545AXB44B4XXWMVQ4W8SBT3HHF"
      ],
      "segment_ids": [
        "1KB9JE5EGJXCW.REACHABLE"
      ],
      "version": 7
    }
  ],
  "cursor": "9dpS093Uy12AzeE"
}
Was this section helpful?

What made this section unhelpful for you?

Delete customer

Deletes a customer profile from a business.

This operation also unlinks any associated cards on file.

As a best practice, you should include the version field in the request to enable optimistic concurrency control. The value must be set to the current version of the customer profile.

To delete a customer profile that was created by merging existing profiles, you must use the ID of the newly created profile.

Header Parameters

Authorizationstring
Content-Typestring

Query Parameters

versionstring

Path Parameters

customer_idstring Required
Was this section helpful?

What made this section unhelpful for you?

DELETE

/v2/customers/{customer_id}?version=11

Select
1 2 3 curl --location --globoff --request DELETE 'https://app.theneo.io/v2/customers/{customer_id}?version=11' \ --header 'Authorization: Bearer ACCESS_TOKEN' \ --header 'Content-Type: application/json'
Was this section helpful?

What made this section unhelpful for you?

Payments / Transaction Examples

All of the stated endpoints and sections are for demonstration purposes only. Theneo does not manage payments API.Get sales data, itemize payments, push orders to POS, and more.

Note: The Orders API provides a one-stop shop for integrating advanced payment functionality. You can itemize payments with custom line items or catalog objects, send orders to real Point of Sale devices to be fulfilled, and more.

In addition, the Orders API allows you to look through all of a seller's previous sales and returns itemization data, customer references, and other information from POS or online transactions.

As an organization, you need to be careful while choosing a payment gateway option. It should be according to the customer’s experience on your websites through to cash flow to online sales. Make sure that you take care of at least 5 things mentioned below while choosing a payment gateway… 

  • Security should be the topmost priority. Make sure that it should be integrated with the 3D security and comply with the PCI Data Security Standard (PCI DSS).

  • Payout Time should be less to credit money in your bank account.

  • Integration need to be easy and simple or it can develop a custom-coded solution for your platform easily.

  • Multiple currencies should be handled by the payment gateway for the customers using different currencies across the world.

Endpoints

POST
PUT
GET
POST
POST
PUT
POST

Hr Management Examples

Leverage all these API to build your own in-app payroll solution, customized for your users' needs

How Are APIs Used By HR Software Providers?

Back in the bad old days before software that's hosted in the Cloud became the norm, APIs were designed to make it possible to connect different legacy software systems, which were often hosted on-premise (within the business location itself). Today, the ways in which APIs are applied is growing exponentially. Organisations with complex digital infrastructures use them to simplify data transfer. HR and ERP software providers use them to integrate seamlessly with other systems like Payroll and Time & Attendance. APIs facilitate data transfers that reduce the manual handling, time, and cost involved in importing and exporting (sharing) data.  

In combination with automated data validation (to check the accuracy and completeness of data that is uploaded to the system), the integrations between HR, Payroll and T&A solutions reduce processing times, decrease error rates, and eliminate the need for data double entry. Essentially, integrations are all about efficiency. They save you time, money, and energy.

APIs as HR and Payroll Software Enhancers

Most HR software Platforms provide APIs that you can use to integrate, automate, and orchestrate data sharing without writing code. In the HR and Payroll spaces, APIs make it easier to integrate and connect systems, services and data, create new user experiences, share information, and authenticate users. They enable transactions and algorithms and let you offer new services.

Using APIs, you can turn your HR software Platform into the source of truth in a digital ecosystem. With the right integrations, your HR Platform forms the hub in a spoke and wheel type configuration for real-time data sharing and improved decision-making across your entire organisation. Another benefit of using an HR HR software Platform (as opposed to stand-alone HR solutions) with a high number of out-of-the-box integrations and an open API is that you will also be less dependent on any one vendor for managing the processes and tasks your business needs to digitise, automate and optimise. If you don’t like that particular product or service at some point in the future, or a better one becomes available, you can simply switch out one solution in your ecosystem for another via the API.

When you access pre-existing integrations through the vendor API instead of having new ones built (which might require the time and cost of a Developer), you save your business time and money. Here's an estimate of what it costs to build a custom API from scratch:

“An enterprise API costs an estimated $25,000-$30,000 to build, and then 50% of that amount per year to manage. Multiply that by 10 APIs and you have $275,000-$450,000 per year just so APIs can exist within your organisation. Everyone who wants to access an API must develop, test and implement custom code, at an estimated cost of $15,000 per integration, plus a 50% maintenance fee. Each API must also be secured, costing additional thousands of dollars.” 

No matter how sophisticated your HR solution (or suite of solutions) is, it will never cover all of the services you need or want to offer to your employees. Sometimes it will be necessary to exchange data with another service. Payroll is an excellent example. Or, you might want to make a completely new service available and that vendor only offers it through an API. APIs also happen to make life easier for your employees - if your HR software provider offers single sign-on, that means you can combine access to all the different software products you use via a single logon - meaning you give your people one place to go and help themselves to al the different business systems they need.

Endpoints

POST
DELETE
GET
PUT
POST
PATCH
DELETE
POST