NAV Navbar
cUrl

Getting started

Welcome to The Nutcache API! Use this API to easily interact with your Nutcache account programmatically. This guide offers a comprehensive suite of developer resources and web services to connect Nutcache to your existing tools and workflow.

Public key

To use the Nutcache API, an owner must first generate a public key. This action can be done directly in Nutcache under the "My account -> Profile" menu. From the "Profile" dialog, select the "MANAGE API KEYS" tab and click the "+ API Key" to continue.

Manage API Keys

Authentication

Authentication info must be provided along with your request within the Authorization header. The authentication is made of the public key, a username and password, all separated by a colon. The authentication info must be encoded in Base 64.

Authorization: nut-basic [Base64(public-key:username:password)]

Organization context

Example

curl -H "Authorization: YVl6T1JtbkdpMHhwaXhCdTQ5b3l6bUpqR29GY2Z3Z1Eycnh2aGl0dDpudXRjYWNoZTFAZ21haWwuY29tOkR5bmFjb20xMjM="
     -H "api-version: 3" 
     -H "OrganizationGuid: 846E176E-7C4B-4BFD-A894-C98F2988927E"
     -X GET https://apps.nutcache.com/webapi/customers

An organization context is required when making requests. To do this, simply include the organization GUID, which can be retrieved via the Organization API from the request header.

Schema

Blank Fields:
Blank fields are made null instead of being omitted.

Timestamps:
All timestamps are returned in the UTC format, YYYY-MM-DDTHH:MM:SSZ. For example, 2016-02-13T23:27:49Z

Date Fields:
Input for date fields is expected to be in one of the following formats:
YYYY-MM-DD
YYYY-MM-DDTHH:MM
YYYY-MM-DDTHH:MMZ
YYYY-MM-DDTHH:MM:SS
YYYY-MM-DDTHH:MM:SSZ
YYYY-MM-DDTHH:MM:SS±hh:mm
YYYY-MM-DDTHH:MM:SS±hh
YYYY-MM-DDTHH:MM:SS±hhmm
If the time zone information is not present, it will be assumed to be in UTC.
A few valid date fields - 2016-02-15T21:16:25Z , 2012-12-24T12:56:15+05:30, 2010-03-23T12:00

Embedding

Example

curl -H 'Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6ckpqR2ZGY2Z3Z1Eycnh2aGl0ZDphcGlkb2NzQGFwaWRvY3MuY29tOnBhc3N3b3Jk' 
     -H 'api-version: 3' 
     -H 'CompanyGuid: 846E176E-7C4B-4BFD-A894-C98F2988927E' 
     -X GET https://apps.nutcache.com/webapi/projects?include=organizations

You can request for additional entities using the "include" keyword up to one level. For example, you can embed an organization entity when requesting a list of projects.

Pagination

Example

curl -H "Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6ckpqR2ZGY2Z3Z1Eycnh2aGl0ZDphcGlkb2NzQGFwaWRvY3MuY29tOnBhc3N3b3Jk" 
     -H "api-version: 3" 
     -H "OrganizationGuid: 846E176E-7C4B-4BFD-A894-C98F2988927E" 
     -X GET "https://apps.nutcache.com/webapi/customers?limit=10&page=2

API responses that return a list of objects, such as Projects, Customers or Time Entries are paginated. To scroll through the pages, add the parameter page to the query string. The page number starts with 1. By default, the number of objects returned per page is 10 and is limited to 100.

Rate Limit

A rate limit of 20 000 API calls per API key is allowed.
If you go over this limit, Nutcache will start returning a HTTP 429 Too Many Requests error, and a Retry-After HTTP header containing the number of seconds until you can retry.

HTTP/1.1 429 Too Many Requests Retry-After: 30

Countries

Get information about countries.

Using the API allows you to do the following with a country data.

Attribute Type Description
code string Country three letter code.
currency number Unique identifier for a currency.
date_format number Enum for date format set for the country:
0 = ISO format (yyyy-MM-dd)
1 = US format w/ dash (MM-dd-yyyy)
2 = US format w/ slash (MM/dd/yyyy)
3 = International format w/ dash(dd-MM-yyyy)
4 = International format w/ slash(dd/MM/yyyy)
5 = International format w/ dots(dd.MM.yyyy)
id number Unique identifier.
name_dede string Country name in Germain.
name_enus string Country name in US english.
name_eses string Country name in Spanish.
name_esus string Country name in Spanish / US.
name_frca string Country name in French / Canada.
name_frfr string Country name in French / France.
name_itit string Country name in Italian.
name_plpl string Country name in Polish.
name_ptbr string Country name in Portuguese.
name_ruru string Country name in Russian.
short_code string Country two letter code.
time_format number Enum for time format set for the organization:
0 = ISO format (HH:mm),
1 = AM/PM format (hh:mm tt)
type countries Type of response.

Viewing a country

Example

curl -H 'Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6bUpqR29GY2Z3Z1Eycnh2aGl0dDpudXRjYWNoZTFAZ21haWwuY29tOkR5bmFjb20xMjM=' 
     -H 'api-version: 3' 
     -X GET https://apps.nutcache.com/webapi/countries/231

Response

{
  "countries": [
    {
      "type": "countries",
      "id": 231,
      "code": "USA",
      "short_code": "US",
      "currency": 147,
      "date_format": 1,
      "time_format": 1,
      "name_enus": "United States",
      "name_frfr": "États-Unis",
      "name_frca": "États-Unis",
      "name_ruru": "Соединенные Штаты Америки",
      "name_ptbr": "Estados Unidos",
      "name_plpl": "Stany Zjednoczone",
      "name_itit": "Stati Uniti",
      "name_eses": "Estados Unidos",
      "name_esus": "Estados Unidos",
      "name_dede": "Vereinigte Staaten von Amerika",
      "links": [
        {
          "href": "countries/231",
          "rel": "self",
          "type": "GET"
        }
      ]
    }
  ]
}

This API allows you to view the details of a country.

GET /webapi/countries/[id]

Parameter Description
id Unique identifier of the country.

List all countries

Example

curl -H 'Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6bUpqR29GY2Z3Z1Eycnh2aGl0dDpudXRjYWNoZTFAZ21haWwuY29tOkR5bmFjb20xMjM=' 
     -H 'api-version: 3' 
     -X GET https://apps.nutcache.com/webapi/countries?limit=2&page=20

Response

{
  "links": [
    {
      "href": "countries?limit=2&page=19",
      "rel": "navigation-previous",
      "type": "GET"
    },
    {
      "href": "countries?limit=2&page=21",
      "rel": "navigation-next",
      "type": "GET"
    }
  ],
  "countries": [
    {
      "type": "countries",
      "id": 39,
      "code": "CMR",
      "short_code": "CM",
      "currency": 154,
      "date_format": 0,
      "time_format": 0,
      "name_enus": "Cameroon",
      "name_frfr": "Cameroun",
      "name_frca": "Cameroun",
      "name_ruru": "Камерун",
      "name_ptbr": "Camarões",
      "name_plpl": "Kamerun",
      "name_itit": "Camerun",
      "name_eses": "Camerún",
      "name_esus": "Camerún",
      "name_dede": "Kamerun",
      "links": [
        {
          "href": "countries/39",
          "rel": "self",
          "type": "GET"
        }
      ]
    },
    {
      "type": "countries",
      "id": 40,
      "code": "CAN",
      "short_code": "CA",
      "currency": 25,
      "date_format": 0,
      "time_format": 0,
      "name_enus": "Canada",
      "name_frfr": "Canada",
      "name_frca": "Canada",
      "name_ruru": "Канада",
      "name_ptbr": "Canadá",
      "name_plpl": "Kanada",
      "name_itit": "Canada",
      "name_eses": "Canadá",
      "name_esus": "Canadá",
      "name_dede": "Kanada",
      "links": [
        {
          "href": "countries/40",
          "rel": "self",
          "type": "GET"
        }
      ]
    }
  ]
}

Using this API, you can fetch a list of countries.

GET /webapi/countries

Country states

Example

curl -H 'Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6ckpqR2ZGY2Z3Z1Eycnh2aGl0ZDphcGlkb2NzQGFwaWRvY3MuY29tOnBhc3N3b3Jk' 
     -H 'api-version: 3'     
     -X GET https://apps.nutcache.com/webapi/countries/231/states

Response

{
  "links": [
    {
      "href": "countries/231/states?limit=10&page=1",
      "rel": "navigation-previous",
      "type": "GET"
    },
    {
      "href": "countries/231/states?limit=10&page=3",
      "rel": "navigation-next",
      "type": "GET"
    }
  ],
  "states": [
    {
      "type": "states",
      "id": 11,
      "country": 231,
      "code": "US_NJ",
      "name_enus": "New Jersey",
      "name_frfr": "New Jersey",
      "name_frca": "New Jersey",
      "name_ruru": "Нью-Джерси",
      "name_ptbr": "Nova Jérsei",
      "name_plpl": "New Jersey",
      "name_itit": "New Jersey",
      "name_eses": "Nueva Jersey",
      "name_esus": "Nueva Jersey",
      "name_dede": "New Jersey",
      "links": [
        {
          "href": "countries/231",
          "rel": "countries",
          "type": "GET"
        }
      ]
    },
    {
      "type": "states",
      "id": 12,
      "country": 231,
      "code": "US_NY",
      "name_enus": "New York",
      "name_frfr": "New York",
      "name_frca": "New York",
      "name_ruru": "Нью-Йорк",
      "name_ptbr": "Nova York",
      "name_plpl": "Nowy Jork",
      "name_itit": "New York",
      "name_eses": "Nueva York",
      "name_esus": "Nueva York",
      "name_dede": "New York",
      "links": [
        {
          "href": "countries/231",
          "rel": "countries",
          "type": "GET"
        }
      ]
    }
  ]
}

This endpoint retrieves the states/provinces of a country.

GET /webapi/countries/[id]/states

Parameter Description
id Unique identifier of the country.

Includes (Countries)

Example

curl -H 'Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6bUpqR29GY2Z3Z1Eycnh2aGl0dDpudXRjYWNoZTFAZ21haWwuY29tOkR5bmFjb20xMjM=' 
     -H 'api-version: 3' 
     -X GET https://apps.nutcache.com/webapi/countries/231?includes=currencies

The following entity types can be included in this payload type:

Type Description
currencies The currency associated with this country.

Customers

An individual or party with whom you conduct business.

Using the API allows you to do the following with customer data.

Attribute Type Description
address string Address.
city string Name of the city.
communication_culture_code string Communication culture code.
Format: [language]-[country code].
organization number Unique identifier for an organization.
contact string Contact name.
country number Unique identifier for a country.
currency number Unique identifier for a currency.
email string Email address.
id number Unique identifier.
legal_notice string Registration number for the customer.
mobile_phone string Mobile phone number.
name string Name of the customer.
phone string Phone number.
state number Unique identifier for a state.
status number Enum for the status of the customer:
0 = Active.
1 = Inactive.
tax number Unique identifier for a tax.
type customers Type of response.
zip_code string Zip code.

Viewing a customer

Example

curl -H "Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6ckpqR2ZGY2Z3Z1Eycnh2aGl0ZDphcGlkb2NzQGFwaWRvY3MuY29tOnBhc3N3b3Jk" 
     -H "api-version: 3" 
     -H "OrganizationGuid: 846E176E-7C4B-4BFD-A894-C98F2988927E" 
     -X GET https://apps.nutcache.com/webapi/customers/154528

Response

{
  "customers": [
    {
      "type": "customers",
      "id": 154528,
      "organization": 9244,
      "name": "Client #1",
      "status": 0,
      "links": [
        {
          "href": "organizations/9244",
          "rel": "organizations",
          "type": "GET"
        },
        {
          "href": "countries/231",
          "rel": "countries",
          "type": "GET"
        },
        {
          "href": "states/2",
          "rel": "states",
          "type": "GET"
        },
        {
          "href": "customers/154528",
          "rel": "self",
          "type": "GET"
        }
      ],
      "email": "xhbdv260psct@claimab.com",
      "contact": "Daron D Barrett",
      "address": "4992  Worley Avenue",
      "city": "Richmond",
      "zip_code": "23223",
      "phone": "434-378-0004",
      "mobile_phone": "703-725-9475",
      "country": 231,
      "state": 2,
      "legal_notice": "987654321",
      "communication_culture_code": "en-US",
      "tax": 11591,
      "currency": 147
    }
  ]
}

This API allows you to view the details of a customer.

GET /webapi/customers/[id]

Parameter Description
id Unique identifier of the customer.

List all customers

Example

curl -H "Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6ckpqR2ZGY2Z3Z1Eycnh2aGl0ZDphcGlkb2NzQGFwaWRvY3MuY29tOnBhc3N3b3Jk" 
     -H "api-version: 3" 
     -H "OrganizationGuid: 846E176E-7C4B-4BFD-A894-C98F2988927E" 
     -X GET https://apps.nutcache.com/webapi/customers

Response

{
  "links": [
    {
      "href": "customers?limit=10&page=2",
      "rel": "navigation-next",
      "type": "GET"
    }
  ],
  "customers": [
    {
      "type": "customers",
      "id": 143222,
      "organization": 1686,
      "name": "Sample client",
      "status": 0,
      "links": [
        {
          "href": "organizations/1686",
          "rel": "organizations",
          "type": "GET"
        },
        {
          "href": "countries/40",
          "rel": "countries",
          "type": "GET"
        },
        {
          "href": "customers/143222",
          "rel": "self",
          "type": "GET"
        }
      ],
      "email": "143222@example.com",
      "contact": "Sample contact name",
      "address": null,
      "city": null,
      "zip_code": null,
      "phone": "123-456-7890",
      "mobile_phone": null,
      "country": 40,
      "state": null,
      "legal_notice": null,
      "communication_culture_code": null,
      "tax": null,
      "currency": null
    }
}

Using this API, you can fetch a list of customers.

GET /webapi/customers

Includes (Customers)

Example

curl -H "Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6ckpqR2ZGY2Z3Z1Eycnh2aGl0ZDphcGlkb2NzQGFwaWRvY3MuY29tOnBhc3N3b3Jk" 
     -H "api-version: 3" 
     -H "OrganizationGuid: 846E176E-7C4B-4BFD-A894-C98F2988927E" 
     -X GET https://apps.nutcache.com/webapi/customers/154528?includes=countries,states

The following entity types can be included in this payload type:

Type Description
organizations The organization containing the customer.
countries The country associated with this customer.
currencies The currency associated with this customer.
states The state associated with this customer.
taxes The tax associated with this customer.

Currencies

Get information about currencies.

Using the API allows you to do the following with currency data.

Attribute Type Description
code string Currency code.
decimal_count number Number of decimal places.
id number Unique identifier.
name_dede string Currency name in German.
name_enus string Currency name in US english.
name_eses string Currency name in Spanish.
name_esus string Currency name in Spanish / US.
name_frca string Currency name in French / Canada.
name_frfr string Currency name in French / France.
name_itit string Currency name in Italian.
name_plpl string Currency name in Polish.
name_ptbr string Currency name in Portuguese.
name_ruru string Currency name in Russian.
type currencies Type of response.

Viewing a currency

Example

curl -H 'Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6bUpqR29GY2Z3Z1Eycnh2aGl0dDpudXRjYWNoZTFAZ21haWwuY29tOkR5bmFjb20xMjM=' 
     -H 'api-version: 3' 
     -X GET https://apps.nutcache.com/webapi/currencies/147

Response

{
  "currencies": [
    {
      "type": "currencies",
      "id": 147,
      "code": "USD",
      "decimal_count": 2,
      "name_enus": "Dollar - United States of America",
      "name_frfr": "Dollar - Etats-Unis d'Amérique",
      "name_frca": "Dollar - Etats-Unis d'Amérique",
      "name_ruru": "Доллар - Соединенные Штаты Америки",
      "name_ptbr": "Dólar - Estados Unidos da América",
      "name_plpl": "dolar amerykański – Stany Zjednoczone",
      "name_itit": "Dollaro - Stati Uniti d'America",
      "name_eses": "Dólar - Estados Unidos",
      "name_esus": "Dólar - Estados Unidos",
      "name_dede": "Dollar - Vereinigten Staaten von Amerika"
    }
  ]
}

This API allows you to view the details of a currency.

GET /webapi/currencies/[id]

Parameter Description
id Unique identifier of the currency.

List all currencies

Example

curl -H 'Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6bUpqR29GY2Z3Z1Eycnh2aGl0dDpudXRjYWNoZTFAZ21haWwuY29tOkR5bmFjb20xMjM=' 
     -H 'api-version: 3' 
     -X GET https://apps.nutcache.com/webapi/currencies?limit=2&page=13

Response

{
  "links": [
    {
      "href": "currencies?limit=2&page=12",
      "rel": "navigation-previous",
      "type": "GET"
    },
    {
      "href": "currencies?limit=2&page=14",
      "rel": "navigation-next",
      "type": "GET"
    }
  ],
  "currencies": [
    {
      "type": "currencies",
      "id": 25,
      "code": "CAD",
      "decimal_count": 2,
      "name_enus": "Dollar - Canada",
      "name_frfr": "Dollar - Canada",
      "name_frca": "Dollar - Canada",
      "name_ruru": "Доллар - Канада",
      "name_ptbr": "Dólar - Canadá",
      "name_plpl": "dolar kanadyjski – Kanada",
      "name_itit": "Dollaro - Canada",
      "name_eses": "Dólar - Canadá",
      "name_esus": "Dólar - Canadá",
      "name_dede": "Kanadischer Dollar – Kanada"
    },
    {
      "type": "currencies",
      "id": 26,
      "code": "CDF",
      "decimal_count": 2,
      "name_enus": "Congolese Franc - Congo/Kinshasa",
      "name_frfr": "Franc congolais - République démocratique du Congo",
      "name_frca": "Franc congolais - République démocratique du Congo",
      "name_ruru": "Конголезский франк - Конго/Киншаса",
      "name_ptbr": "Franco Congolês - Congo/Kinshasa",
      "name_plpl": "frank kongijski – Kongo/Kinszasa",
      "name_itit": "Franco - Congo/Kinshasa",
      "name_eses": "Franco congoleño - Congo/Kinsasa",
      "name_esus": "Franco congoleño - Congo/Kinsasa",
      "name_dede": "Kongo-Franc – Demokratische Republik Kongo"
    }
  ]
}

Using this API, you can fetch a list of currencies.

GET /webapi/currencies

Expenses

Describes the expenses incurred in connection with a company's operations, including the expense amount, taxes, suppliers and other people associated with the expense.

Using the API allows you to do the following with with expense data.

Attribute Type Description
amount_after_taxes decimal The total amount to pay, including the taxes.
amount_before_taxes decimal The subtotal amount, without the taxes.
amount_due decimal The outstanding amount.
amount_paid decimal The amount already paid.
billable boolean Expense is billable.
description string Description.
due_date date The expense due date.
expense_date date The expense date.
expense_number string Unique number for the expense.
id number Unique identifier.
invoice number Unique identifier of an invoice
member number Unique identifier of a member.
organization number Unique identifier for an organization.
project number Unique identifier of a project.
status number Enum for the expense status:
0 = To pay.
1 = Partially paid.
2 = Paid.
3 = Deleted.
taxes_amount decimal Amount of taxes to paid.
type expenses Type of response.

Viewing an expense

Example


curl -H 'Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6ckpqR2ZGY2Z3Z1Eycnh2aGl0ZDphcGlkb2NzQGFwaWRvY3MuY29tOnBhc3N3b3Jk' 
     -H 'api-version: 3' 
     -H "OrganizationGuid: 846E176E-7C4B-4BFD-A894-C98F2988927E" 
     -X GET https://apps.nutcache.com/webapi/expenses/234359

Response


{
  "expenses": [
    {
      "type": "expenses",
      "id": 234359,
      "expense_number": "0010",
      "expense_date": "2018-10-03T00:00:00",
      "organization": 9244,
      "links": [
        {
          "href": "organizations/9244",
          "rel": "organizations",
          "type": "GET"
        },
        {
          "href": "projects/20196",
          "rel": "projects",
          "type": "GET"
        },
        {
          "href": "expenses/234359",
          "rel": "self",
          "type": "GET"
        }
      ],
      "billable": false,
      "description": null,
      "due_date": "2018-10-31T00:00:00",
      "status": 0,
      "amount_after_taxes": 105,
      "amount_before_taxes": 100,
      "amount_due": 105,
      "amount_paid": 0,
      "taxes_amount": 5,
      "project": 20196,
      "member": 29550,
      "invoice": null
    }
  ]
}

This API allows you to view the details of a expense.

GET /webapi/expenses/[id]

Parameter Description
id Unique identifier of the expense.

List all expenses

Example


curl -H 'Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6ckpqR2ZGY2Z3Z1Eycnh2aGl0ZDphcGlkb2NzQGFwaWRvY3MuY29tOnBhc3N3b3Jk' 
     -H 'api-version: 3' 
     -H "OrganizationGuid: 846E176E-7C4B-4BFD-A894-C98F2988927E" 
     -X GET https://apps.nutcache.com/webapi/expenses/

Response


{
  "links": [
    {
      "href": "expenses?limit=2&page=2",
      "rel": "navigation-previous",
      "type": "GET"
    },
    {
      "href": "expenses?limit=2&page=4",
      "rel": "navigation-next",
      "type": "GET"
    }
  ],
  "expenses": [
    {
      "type": "expenses",
      "id": 234354,
      "expense_number": "0005",
      "expense_date": "2018-10-03T00:00:00",
      "organization": 9244,
      "links": [
        {
          "href": "organizations/9244",
          "rel": "organizations",
          "type": "GET"
        },
        {
          "href": "expenses/234354",
          "rel": "self",
          "type": "GET"
        }
      ],
      "billable": false,
      "description": null,
      "due_date": "2018-10-03T00:00:00",
      "status": 0,
      "amount_after_taxes": 8,
      "amount_before_taxes": 8,
      "amount_due": 8,
      "amount_paid": 0,
      "taxes_amount": 0,
      "project": null,
      "member": 29550,
      "invoice": null
    }
  ]
}

Using this API, you can fetch a list of expenses.

GET /webapi/expenses/

Expense taxes

Example


curl -H 'Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6ckpqR2ZGY2Z3Z1Eycnh2aGl0ZDphcGlkb2NzQGFwaWRvY3MuY29tOnBhc3N3b3Jk' 
     -H 'api-version: 3' 
     -H "OrganizationGuid: 846E176E-7C4B-4BFD-A894-C98F2988927E" 
     -X GET https://apps.nutcache.com/webapi/expenses/234300/expense_taxes

Response


{
  "expense_taxes": [
    {
      "type": "expense_taxes",
      "expense": 234359,
      "id": 229029,
      "tax_amount": 5,
      "tax_code": "A tax",
      "links": [
        {
          "href": "expenses/234359",
          "rel": "expenses",
          "type": "GET"
        }
      ]
    }
  ]
}

If you want to get a detailed list of taxes for an expense:

GET /webapi/expenses/[id]/expense_taxes

Parameter Description
id Unique identifier of the expense.
Attribute Type Description
expense number Unique identifier of the expense.
id number Unique identifier.
tax_amount decimal The amount to be paid.
tax_code string The name or code.
type expense_taxes Type of response.

Includes (Expenses)

Example


curl -H 'Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6ckpqR2ZGY2Z3Z1Eycnh2aGl0ZDphcGlkb2NzQGFwaWRvY3MuY29tOnBhc3N3b3Jk' 
     -H 'api-version: 3' 
     -H "OrganizationGuid: 846E176E-7C4B-4BFD-A894-C98F2988927E" 
     -X GET https://apps.nutcache.com/webapi/expenses/234359?includes=customers

The following entity types can be included in this payload type:

Type Description
organizations The organization containing this expense.
customers The customer associated with this expense.
invoices The invoice associated with this expense.
expense_taxes The taxes associated to this expense.

Invoices

A document sent to a customer that includes a list of products sold or tasks provided, with a statement of the sum due.

Using the API allows you to do the following with invoice data.

Attribute Type Description
balance decimal The customer due amount.
customer number Unique identifier for a customer.
customer_address string The customer address linked to the invoice.
customer_city string The customer city linked to the invoice.
customer_email string The customer email linked to the invoice.
customer_legal_notice string The customer registration number linked to the invoice.
customer_phone string The customer phone linked to the invoice.
customer_phone_mobile string The customer mobile phone linked to the invoice.
customer_postal_zip_code string The customer zip code linked to the invoice.
customer_province_state string The customer state linked to the invoice.
description string Description.
due_date datetime The customer due date.
estimate number Unique identifier for an estimate.
id number Unique identifier.
invoice_date datetime Date.
invoice_number string Document number.
notes string Notes visible to the customer.
organization number Unique identifier for an organization.
paid_to_date decimal Amount paid by the customer.
purchase_order string Purchase order.
responsible number Unique identifier for a member responsible for the invoice.
status number Enum for the invoice status :
0 = Draft.
1 = Sent.
2 = Viewed.
3 = Partially paid.
4 = Paid.
5 = Disputed.
6 = Void.
7 = Deleted.
taxes_amount decimal Amount of taxes to paid.
terms string Terms.
total decimal Total amount.
total_amount_before_taxes decimal Total amount before taxes.
type invoices Type of response.

Viewing an invoice

Example

curl -H 'Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6ckpqR2ZGY2Z3Z1Eycnh2aGl0ZDphcGlkb2NzQGFwaWRvY3MuY29tOnBhc3N3b3Jk' 
     -H 'api-version: 3' 
     -H 'OrganizationGuid: 846E176E-7C4B-4BFD-A894-C98F2988927E' 
     -X GET https://apps.nutcache.com/webapi/invoices/9287

Response

{
    "invoices": [
        {
            "type":"invoices",
            "id":9287,
            "invoice_number":"0005",
            "customer_name":"Sample client",
            "balance":1225.7900,
            "paid_to_date":100.0000,
            "organization":1686,
            "customer":143222,
            "customer_address":null,
            "customer_city":null,
            "customer_contact":"Sample contact name",
            "customer_country":"Canada",
            "customer_email":"143222@example.com",
            "customer_legal_notice":null,
            "customer_phone":"123-456-7890",
            "customer_phone_mobile":null,
            "customer_postal_zip_code":null,
            "customer_province_state":null,
            "custom_title":null,
            "description":null,
            "due_date":"2018-04-18T00:00:00",
            "estimate":null,
            "invoice_date":"2018-04-18T00:00:00",
            "notes":null,
            "terms":null,
            "purchase_order":null,
            "responsible":9015,
            "status":3,
            "taxes_amount":13.7900,
            "total":1325.7900,
            "total_amount_before_taxes":1312.0000,
            "links":[
                {
                "href":"organizations/1686",
                "rel":"organizations",
                "type":"GET"
                },
                {
                "href":"customers/143222",
                "rel":"customers",
                "type":"GET"
                },
                {
                "href":"invoices/9287",
                "rel":"self",
                "type":"GET"
                }
            ]
        }
    ]
}

This API allows you to view an invoice.

GET /webapi/invoices/[id]

Parameter Description
id Unique identifier of the invoice.

List all invoices

Example

curl -H 'Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6ckpqR2ZGY2Z3Z1Eycnh2aGl0ZDphcGlkb2NzQGFwaWRvY3MuY29tOnBhc3N3b3Jk' 
     -H 'api-version: 3' 
     -H 'OrganizationGuid: 846E176E-7C4B-4BFD-A894-C98F2988927E' 
     -X GET https://apps.nutcache.com/webapi/invoices

Response

{
  "links": [
    {
      "href": "invoices?limit=1&page=1",
      "rel": "navigation-previous",
      "type": "GET"
    },
    {
      "href": "invoices?limit=1&page=3",
      "rel": "navigation-next",
      "type": "GET"
    }
  ],
  "invoices": [
    {
      "type": "invoices",
      "id": 14654,
      "invoice_number": "0002",
      "customer_name": "Client 1",
      "balance": 51.5,
      "paid_to_date": 0,
      "organization": 9244,
      "customer": 154528,
      "customer_address": null,
      "customer_city": null,
      "customer_contact": null,
      "customer_country": "Canada",
      "customer_email": null,
      "customer_legal_notice": null,
      "customer_phone": null,
      "customer_phone_mobile": null,
      "customer_postal_zip_code": null,
      "customer_province_state": null,
      "custom_title": null,
      "description": null,
      "due_date": "2018-09-20T00:00:00",
      "estimate": null,
      "invoice_date": "2018-09-20T00:00:00",
      "notes": null,
      "terms": null,
      "purchase_order": null,
      "responsible": 29550,
      "status": 0,
      "taxes_amount": 1.5,
      "total": 51.5,
      "total_amount_before_taxes": 50,
      "links": [
        {
          "href": "organizations/9244",
          "rel": "organizations",
          "type": "GET"
        },
        {
          "href": "customers/154528",
          "rel": "customers",
          "type": "GET"
        },
        {
          "href": "invoices/14654",
          "rel": "self",
          "type": "GET"
        }
      ]
    }
  ]
}

Using this API, you can fetch a list of invoices.

GET /webapi/invoices/

Invoice details

Example

curl -H 'Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6ckpqR2ZGY2Z3Z1Eycnh2aGl0ZDphcGlkb2NzQGFwaWRvY3MuY29tOnBhc3N3b3Jk' 
     -H 'api-version: 3' 
     -H 'OrganizationGuid: 846E176E-7C4B-4BFD-A894-C98F2988927E' 
     -X GET https://apps.nutcache.com/webapi/invoices/9287/invoice_details

Response

{
    "invoice_details":
    [
        {
            "type":"invoice_details",
            "id":23926,
            "description":"Administration - taxable",
            "quantity":1.0000,
            "price":40.0000,
            "total_price":40.0000,
            "invoice_detail_type":1,
            "project":7224,
            "links":
                [
                    {
                    "href":"projects/7224",
                    "rel":"projects",
                    "type":"GET"
                    },
                    {
                    "href":"invoices/9287",
                    "rel":"invoices",
                    "type":"GET"
                    }
                ],
            "item":337523,
            "tax":376,
            "invoice":9287
        }
    ]
}

This endpoint retrieves the invoice details.

GET /webapi/invoices/[id]/invoice_details

Parameter Description
id Unique identifier of the invoice.
Attribute Type Description
description string Description.
id number Unique identifier for an invoice detail.
invoice number Unique identifier for an invoice.
invoice_detail_type number Enum for invoice detail type:
0 = Product.
1 = Task.
item number Unique identifier for an item.
price decimal Rate/Unit price.
project number Unique identifier for a project.
quantity decimal Units/Quantity
tax number Unique identifier for an invoice tax.
total_price decimal Total price.
type invoice_details Type of response.

Invoice taxes

Example

curl -H 'Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6ckpqR2ZGY2Z3Z1Eycnh2aGl0ZDphcGlkb2NzQGFwaWRvY3MuY29tOnBhc3N3b3Jk' 
     -H 'api-version: 3' 
     -H 'OrganizationGuid: 846E176E-7C4B-4BFD-A894-C98F2988927E' 
     -X GET https://apps.nutcache.com/webapi/invoices/9287/invoice_taxes

Response

{
    "invoice_taxes":
    [
        {
            "type":"invoice_taxes",
            "total":7.8000,
            "code":"HST",
            "compound":false,
            "identification":null,
            "rate":0.130000,
            "sequence_number":1,
            "invoice":9287,
            "links":
                [
                    {
                    "href":"invoices/9287",
                    "rel":"invoices",
                    "type":"GET"
                    }
                ],
            "tax":375
            },
            {
            "type":"invoice_taxes",
            "total":3.9900,
            "code":"QST",
            "compound":false,
            "identification":null,
            "rate":0.099750,
            "sequence_number":1,
            "invoice":9287,
            "links":
                [
                    {
                    "href":"invoices/9287",
                    "rel":"invoices",
                    "type":"GET"
                    }
                ],
            "tax":376},
            {
            "type":"invoice_taxes",
            "total":2.0000,
            "code":"GST",
            "compound":false,
            "identification":null,
            "rate":0.050000,
            "sequence_number":2,
            "invoice":9287,
            "links":
                [
                    {
                    "href":"invoices/9287",
                    "rel":"invoices",
                    "type":"GET"
                    }
                ],
            "tax":376
        }
    ]
}

This endpoint retrieves the taxes of an invoice.

GET /webapi/invoices/[id]/invoice_taxes

Parameter Description
id Unique identifier of the invoice.
Attribute Type Description
code string Tax code.
compound boolean True if tax is compound.
identification string Registration / identifier.
invoice number Unique identifier for an invoice.
rate decimal Rate.
sequence_number number Sequence order.
tax number Unique identifier for an invoice tax.
total decimal Total amount for this tax.
type invoice_taxes Type of response.

Includes (Invoices)

Example

curl -H 'Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6ckpqR2ZGY2Z3Z1Eycnh2aGl0ZDphcGlkb2NzQGFwaWRvY3MuY29tOnBhc3N3b3Jk' 
     -H 'api-version: 3' 
     -H 'OrganizationGuid: 846E176E-7C4B-4BFD-A894-C98F2988927E' 
     -X GET https://apps.nutcache.com/webapi/invoices/9287?includes=invoice_details,invoice_taxes

The following entity types can be included in this payload type:

Type Description
organizations The organization containing this invoice
customers The customer associated with this invoice
members The responsible member for this invoice
invoice_details The invoice's detail rows
invoice_taxes The taxes summary of this invoice

Includes (Invoice details)

Example

curl -H 'Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6ckpqR2ZGY2Z3Z1Eycnh2aGl0ZDphcGlkb2NzQGFwaWRvY3MuY29tOnBhc3N3b3Jk' 
     -H 'api-version: 3' 
     -H 'OrganizationGuid: 846E176E-7C4B-4BFD-A894-C98F2988927E' 
     -X GET https://apps.nutcache.com/webapi/invoices/9287/invoice_details?includes=projects

The following entity types can be included in this payload type:

Type Description
invoices The invoice associated with this invoice detail.
items The item associated with this invoice detail.
projects The project associated with this invoice details.

Includes (Invoice taxes)

Example

curl -H 'Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6ckpqR2ZGY2Z3Z1Eycnh2aGl0ZDphcGlkb2NzQGFwaWRvY3MuY29tOnBhc3N3b3Jk' 
     -H 'api-version: 3' 
     -H 'OrganizationGuid: 846E176E-7C4B-4BFD-A894-C98F2988927E' 
     -X GET https://apps.nutcache.com/webapi/invoices/9287/invoice_taxes?includes=taxes

The following entity types can be included in this payload type:

Type Description
invoices The invoice associated with this invoice detail.
taxes The tax associated with this invoice detail.

Organizations

A Nutcache organization is an entity comprising multiple members with various roles and projects with varying constraints and goals.

Using the API allows you to do the following with organization data.

Attribute Type Description
active_user_count number Number of active members.
address string Address.
city string Name of the city.
country number Unique identifier for a country.
currency number Unique identifier for a currency.
date_format number Enum for date format set for the organization:
0 = ISO format (yyyy-MM-dd).
1 = US format w/ dash (MM-dd-yyyy).
2 = US format w/ slash (MM/dd/yyyy).
3 = International format w/ dash(dd-MM-yyyy).
4 = International format w/ slash(dd/MM/yyyy).
5 = International format w/ dots(dd.MM.yyyy).
email string Email contact.
guid string Alternative unique identifier.
id number Unique identifier.
is_demo boolean Indicates if the organization is for demo purposes.
is_owner boolean Indicates if the current user is the owner.
last_activity_date datetime Last date/time this organization was accessed.
logo_url string URL for organization logo.
name string Name of the organization.
notification_count number Number of notifications.
phone string Phone number.
state state Unique identifier for a state.
status number Enum for the status of the organization:
0 = Active.
1 = Inactive.
2 = Expired.
time_format number Enum for time format set for the organization:
0 = ISO format (HH:mm).
1 = AM/PM format (hh:mm tt).
time_rounding number Enum for time rounding set for time entries in the organization:
0 = None.
1 = Round to nearest.
2 = Round up to nearest.
time_rounding_minutes number Number, in minutes, set to automatically round time entries, if time rounding is set.
time_span_format number Enum for duration (time) format set for the organization:
0 = Decimal (e.g. 2.5).
1 = Short time (e.g. 2:30).
time_tracking_type number Enum for time tracking mode set for the organization:
0 = Duration.
1 = Start/End time.
type organizations Type of response.
website string Site identifier for the organization.
zip_code string Zip code.

Viewing an organization

Example


curl -H 'Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6ckpqR2ZGY2Z3Z1Eycnh2aGl0ZDphcGlkb2NzQGFwaWRvY3MuY29tOnBhc3N3b3Jk' 
     -H 'api-version: 3' 
     -X GET https://apps.nutcache.com/webapi/organizations/6745

Response


{
  "organizations": [
    {
      "type": "organizations",
      "id": 1660,
      "guid": "7b1fb609-eba9-4b4d-91a8-b136cecaddaf",
      "name": "Green Bay Packers",
      "email": "1660@example.com",
      "address": null,
      "city": null,
      "zip_code": null,
      "phone": null,
      "country": 4,
      "state": null,
      "currency": 3,
      "website": null,
      "logo_url": "",
      "last_activity_date": "2018-01-11T18:59:50.07",
      "notification_count": 168,
      "is_owner": true,
      "is_demo": false,
      "date_format": 0,
      "time_format": 0,
      "time_span_format": 1,
      "time_rounding": 0,
      "time_rounding_minutes": 0,
      "time_tracking_type": 0,
      "active_user_count": 1,
      "links": [
        {
          "href": "countries/4",
          "rel": "countries",
          "type": "GET"
        },
        {
          "href": "currencies/3",
          "rel": "currencies",
          "type": "GET"
        },
        {
          "href": "organizations/1660",
          "rel": "self",
          "type": "GET"
        }
      ]
    }
  ]
}

This API allows you to view the details of an organization.

GET /webapi/organizations/<id>

Parameter Description
id Unique identifier of the organization.

List all organizations

Example


curl -H 'Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6ckpqR2ZGY2Z3Z1Eycnh2aGl0ZDphcGlkb2NzQGFwaWRvY3MuY29tOnBhc3N3b3Jk' 
     -H 'api-version: 3' 
     -X GET https://apps.nutcache.com/webapi/organizations

Response


{
  "links": [
    {
      "href": "organizations?limit=10&page=1",
      "rel": "navigation-prev",
      "type": "GET"
    },
    {
      "href": "organizations?limit=10&page=3",
      "rel": "navigation-next",
      "type": "GET"
    }
  ],
  "organizations": [
    {
      "type": "organizations",
      "id": 1660,
      "guid": "7b1fb609-eba9-4b4d-91a8-b136cecaddaf",
      "name": "Green Bay Hackers",
      "email": "1660@example.com",
      "address": null,
      "city": null,
      "zip_code": null,
      "phone": null,
      "country": 4,
      "state": null,
      "currency": 3,
      "website": null,
      "logo_url": "",
      "last_activity_date": "2018-01-11T18:59:50.07",
      "notification_count": 167,
      "is_owner": true,
      "is_demo": false,
      "date_format": 0,
      "time_format": 0,
      "time_span_format": 1,
      "time_rounding": 0,
      "time_rounding_minutes": 0,
      "time_tracking_type": 0,
      "active_user_count": 1,
      "links": [
        {
          "href": "countries/4",
          "rel": "countries",
          "type": "GET"
        },
        {
          "href": "currencies/3",
          "rel": "currencies",
          "type": "GET"
        },
        {
          "href": "organizations/1660",
          "rel": "self",
          "type": "GET"
        }
      ]
    }
  ]
}

Using this API, you can fetch a list of organizations.

GET /webapi/organizations

Includes (Organizations)

Example


curl -H 'Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6ckpqR2ZGY2Z3Z1Eycnh2aGl0ZDphcGlkb2NzQGFwaWRvY3MuY29tOnBhc3N3b3Jk' 
     -H 'api-version: 3' 
     -X GET https://apps.nutcache.com/webapi/organizations/6745?includes=countries,states,currencies

The following entity types can be included in this payload type:

Type Description
countries The country associated with this organization.
states The state associated with this organization.
currencies The currency associated with this organization.

Projects

A project is a planned work or activity that is to be completed over a period of time using the Scrum or any other Agile methodology.

Using the API allows you to do the following with project data.

Attribute Type Description
billing_approved_entries_only boolean Only consider approved timesheet entries for project billing.
Available if billing_method <> 0.
billing_invoice_method_fixed_fee decimal Fixed fee for the project.
Available if billing_method = 4.
billing_invoice_method_hourly_rate decimal Fixed hourly rate for the project.
Available if billing_method = 3.
billing_method number Enum for billing method set for the project :
0 = No invoice will be created for this project.
1 = Billable amount is calculated from the services' rate.
2 = Billable amount is calculated from the members' rate.
3 = Billable amount is a fixed-fee.
4 = Billable amount is calculated from a project fixed hourly rate.
budget_approved_only boolean Only consider approved timesheet entries when calculating project budget.
budget_restrictive boolean Budgets cannot be exceeded for the project, allowing for a better control of worked hours and expenses.
budget_scope number Enum for budget scope set for the project:
0 - Global.
1 = Per member [Enterprise only].
2 = Per service [Enterprise only].
budget_type number Enum for budget type set for the project:
0 = Worked hours.
1 = Billable hours.
2 = Costs.
3 = Billable amounts.
customer number Unique identifier for a customer.
description string Description for the project.
display_color string HTML color code to identify the project.
EffectiveBudgetAmount decimal Budget amount of the projet depending on its budget type (budget_type).
EffectiveBudgetMinutes number Budget minutes of the projet depending on its budget type (budget_type).
end_date datetime End date set for the project.
id number Unique identifier.
name string Unique name for the project.
organization number Unique identifier for an organization.
primary_contact_email string Primary contact email.
primary_contact_name string Primary contact name.
primary_contact_phone string Primary contact phone.
project_type number Enum for the type of project:
0 = Agile.
1 = Scrum.
secondary_contact_email string Secondary contact email.
secondary_contact_name string Secondary contact name.
secondary_contact_phone string Secondary contact phone.
start_date datetime Start date set for the project.
status number Enum for the status of the project:
0 = Planned.
1 = In progress.
2 = Completed.
3 = Canceled.
4 = Archived.
type projects Type of response.
vision string Project vision.

Viewing a project

Example

curl -H 'Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6ckpqR2ZGY2Z3Z1Eycnh2aGl0ZDphcGlkb2NzQGFwaWRvY3MuY29tOnBhc3N3b3Jk' 
     -H 'api-version: 3' 
     -H 'OrganizationGuid: 846E176E-7C4B-4BFD-A894-C98F2988927E' 
     -X GET https://apps.nutcache.com/webapi/projects/6640

Response

{
  "projects": [
    {
      "type": "projects",
      "id": 6640,
      "Organization": 1686,
      "code": "Agile sample project (non-billable)",
      "display_color": "#607d8b",
      "status": 1,
      "links": [
        {
          "href": "organizations/1686",
          "rel": "organizations",
          "type": "GET"
        },
        {
          "href": "customers/143222",
          "rel": "customers",
          "type": "GET"
        },
        {
          "href": "projects/6640",
          "rel": "self",
          "type": "GET"
        }
      ],
      "project_type": 0,
      "description": "Leverage the Agile approach to organize and manage your projects with boards.",
      "Vision": "Project vision",
      "primary_contact_email": null,
      "primary_contact_name": null,
      "primary_contact_phone": null,
      "secondary_contact_email": null,
      "secondary_contact_name": null,
      "secondary_contact_phone": null,
      "start_date": "2018-01-22T00:00:00",
      "end_date": null,
      "budget_scope": "1",
      "budget_type": "1",
      "EffectiveBudgetAmount": 0,
      "EffectiveBudgetMinutes": 0,
      "budget_approved_only": false,
      "budget_restrictive": false,
      "billing_method": "NotBillable",
      "billing_invoice_method_fixed_fee": 0,
      "billing_invoice_method_hourly_rate": 0,
      "billing_approved_entries_only": false,
      "customer": 143222,
      "project_budget": null
    }
  ]
}

This API allows you to view the details of a project.

GET /webapi/projects/[id]

Parameter Description
id Unique identifier of the project.

List all projects

Example

curl -H 'Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6ckpqR2ZGY2Z3Z1Eycnh2aGl0ZDphcGlkb2NzQGFwaWRvY3MuY29tOnBhc3N3b3Jk'
     -H 'api-version: 3'
     -H 'OrganizationGuid: 846E176E-7C4B-4BFD-A894-C98F2988927E'
     -X GET https://apps.nutcache.com/webapi/projects

Response

{
  "links": [    
    {
      "href": "projects?limit=10&page=2",
      "rel": "navigation-next",
      "type": "GET"
    }
  ],
  "projects": [
    {
      "type": "projects",
      "id": 6640,
      "Organization": 1686,
      "code": "Agile sample project (non-billable)",
      "display_color": "#607d8b",
      "status": 1,
      "links": [
        {
          "href": "organizations/1686",
          "rel": "organizations",
          "type": "GET"
        },
        {
          "href": "customers/143222",
          "rel": "customers",
          "type": "GET"
        },
        {
          "href": "projects/6640",
          "rel": "self",
          "type": "GET"
        }
      ],
      "project_type": 0,
      "description": "Leverage the Agile approach to organize and manage your projects with boards.",
      "Vision": "Project vision",
      "primary_contact_email": null,
      "primary_contact_name": null,
      "primary_contact_phone": null,
      "secondary_contact_email": null,
      "secondary_contact_name": null,
      "secondary_contact_phone": null,
      "start_date": "2018-01-22T00:00:00",
      "end_date": null,
      "budget_scope": "1",
      "budget_type": "1",
      "EffectiveBudgetAmount": 0,
      "EffectiveBudgetMinutes": 0,
      "budget_approved_only": false,
      "budget_restrictive": false,
      "billing_method": "NotBillable",
      "billing_invoice_method_fixed_fee": 0,
      "billing_invoice_method_hourly_rate": 0,
      "billing_approved_entries_only": false,
      "customer": 143222,
      "project_budget": null
    }
  ]
}

GET /webapi/projects

Using this API, you can fetch a list of projects.

Project members

Example

curl -H 'Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6ckpqR2ZGY2Z3Z1Eycnh2aGl0ZDphcGlkb2NzQGFwaWRvY3MuY29tOnBhc3N3b3Jk'
     -H 'api-version: 3'
     -H 'OrganizationGuid: 846E176E-7C4B-4BFD-A894-C98F2988927E'
     -X GET https://apps.nutcache.com/webapi/projects/6640/project_members

Response

{
  "project_members": [
    {
      "type": "project_members",
      "id": 73582,
      "name": "John Smith",
      "email": "john.smith@example.com",
      "display_color": "#ef6c00",
      "status": 1,
      "project": 6640,
      "links": [
        {
          "href": "projects/6640",
          "rel": "projects",
          "type": "GET"
        }
      ],
      "billing_rate": null,
      "budget_amount": 0,
      "budget_minutes": 0,      
      "member": 29550
    }
  ]
}

This endpoint retrieves the project members for a project.

GET /webapi/projects/[id]/project_members

Parameter Description
id Unique identifier of the project.
Attribute Type Description
billing_rate decimal Billing rate for the project member.
The billing rate is available only if the project invoice method is set to member rate (billing_method = 2).
budget_amount decimal Budget amount set for the member depending on the project budget type (budget_type)
budget_minutes number Budget minutes set for the member depending on the project budget type (budget_type)
display_color string HTML color code to identify the member.
email string Member email.
id number Unique identifier for a project member.
member number Unique identifier for the member of the organization.
name string Member name.
project number Unique identifier for the project.
status number Enum for the status of the member in the project:
0 = Inactive.
1 = Active.
type project_members Type of response.

Project services

Example

curl -H 'Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6ckpqR2ZGY2Z3Z1Eycnh2aGl0ZDphcGlkb2NzQGFwaWRvY3MuY29tOnBhc3N3b3Jk' 
     -H 'api-version: 3' 
     -H 'OrganizationGuid: 846E176E-7C4B-4BFD-A894-C98F2988927E' 
     -X GET https://apps.nutcache.com/webapi/projects/6640/project_services

Response

{
  "project_services": [
    {
      "type": "project_services",
      "id": 130317,
      "description": "A service",
      "order": 0,
      "status": 0,
      "project": 6640,
      "links": [
        {
          "href": "projects/6640",
          "rel": "projects",
          "type": "GET"
        }
      ],
      "notes": "123",
      "billing_rate": 10,
      "budget_amount": 0,
      "budget_minutes": 0,
      "item": null
    }
  ]
}

This endpoint retrieves the project services for a project.

GET /webapi/projects/[id]/project_services

Parameter Description
id Unique identifier of the project.
Attribute Type Description
billing_rate decimal Billing rate for the service in the project.
The billing rate is available only if the project invoice method is set to service rate (billing_method = 2).
budget_amount decimal Budget amount set for the service in the project depending on the budget type of the project (budget_type).
budget_minutes number Budget minutes set for the service in the project depending on the budget type of the project (budget_type).
description string Description for the service in the project.
id number Unique identifier for a service in the project.
item number Unique identifier for the item.
notes string Additional notes for the service in the project.
order number Display order of the project service in the project.
project number Unique identifier for the project.
status number Enum for the status of the service in the project:
0 = Active.
1 = Inactive.
type project_services Type of response.

Includes (Projects)

Example

curl -H 'Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6ckpqR2ZGY2Z3Z1Eycnh2aGl0ZDphcGlkb2NzQGFwaWRvY3MuY29tOnBhc3N3b3Jk' 
     -H 'api-version: 3' 
     -H 'OrganizationGuid: 846E176E-7C4B-4BFD-A894-C98F2988927E' 
     -X GET https://apps.nutcache.com/webapi/projects/6640?includes=customers

The following entity types can be included in this payload type:

Type Description
organizations The organization containing this project.
customers The customer associated with this project.
project_services The services associated with this project.
project_members The members assigned to this project.

Includes (Project members)

Example

curl -H 'Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6ckpqR2ZGY2Z3Z1Eycnh2aGl0ZDphcGlkb2NzQGFwaWRvY3MuY29tOnBhc3N3b3Jk' 
     -H 'api-version: 3' 
     -H 'OrganizationGuid: 846E176E-7C4B-4BFD-A894-C98F2988927E' 
     -X GET https://apps.nutcache.com/webapi/projects/6640/project_members?includes=members

The following entity types can be included in this payload type:

Type Description
members The member associated with this project member.
projects The project associated with this project member.

Includes (Project services)

Example

curl -H 'Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6ckpqR2ZGY2Z3Z1Eycnh2aGl0ZDphcGlkb2NzQGFwaWRvY3MuY29tOnBhc3N3b3Jk' 
     -H 'api-version: 3' 
     -H 'OrganizationGuid: 846E176E-7C4B-4BFD-A894-C98F2988927E' 
     -X GET https://apps.nutcache.com/webapi/projects/6640/project_services?includes=items

The following entity types can be included in this payload type:

Type Description
items The item associated with this project service.
projects The project associated with this project service.

States

Retrieve information about states associated to a country, mostly used for organization and customer payloads.

Using the API allows you to do the following with a state data.

Attribute Type Description
code string State code in the following format:
[Country 2 letter code]-[State code].
country number Unique identifier for a country.
id number Unique identifier.
name_dede string State name in Germain.
name_enus string State name in US english.
name_eses string State name in Spanish.
name_esus string State name in Spanish / US.
name_frca string State name in French / Canada.
name_frfr string State name in French / France.
name_itit string State name in Italian.
name_plpl string State name in Polish.
name_ptbr string State name in Portuguese.
name_ruru string State name in Russian.
type states Type of response.

Viewing a state

Example

curl -H 'Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6bUpqR29GY2Z3Z1Eycnh2aGl0dDpudXRjYWNoZTFAZ21haWwuY29tOkR5bmFjb20xMjM=' 
     -H 'api-version: 3' 
     -X GET https://apps.nutcache.com/webapi/states/12

Response

{
  "states": [
    {
      "type": "states",
      "id": 12,
      "country": 231,
      "code": "US_NY",
      "name_enus": "New York",
      "name_frfr": "New York",
      "name_frca": "New York",
      "name_ruru": "Нью-Йорк",
      "name_ptbr": "Nova York",
      "name_plpl": "Nowy Jork",
      "name_itit": "New York",
      "name_eses": "Nueva York",
      "name_esus": "Nueva York",
      "name_dede": "New York",
      "links": [
        {
          "href": "countries/231",
          "rel": "countries",
          "type": "GET"
        }
      ]
    }
  ]
}

This API allows you to view the details of a state.

GET /webapi/states/[id]

Parameter Description
id Unique identifier of the state.

List all states

Example

curl -H 'Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6bUpqR29GY2Z3Z1Eycnh2aGl0dDpudXRjYWNoZTFAZ21haWwuY29tOkR5bmFjb20xMjM=' 
     -H 'api-version: 3' 
     -X GET https://apps.nutcache.com/webapi/states?limit=2&page=26

Response

{
  "links": [
    {
      "href": "states?limit=2&page=25",
      "rel": "navigation-previous",
      "type": "GET"
    },
    {
      "href": "states?limit=2&page=27",
      "rel": "navigation-next",
      "type": "GET"
    }
  ],
  "states": [
    {
      "type": "states",
      "id": 51,
      "country": 231,
      "code": "US_SC",
      "name_enus": "South Carolina",
      "name_frfr": "Caroline du Sud",
      "name_frca": "Caroline du Sud",
      "name_ruru": "Южная Каролина",
      "name_ptbr": "Carolina do Sul",
      "name_plpl": "Karolina Południowa",
      "name_itit": "Carolina del Sud",
      "name_eses": "Carolina del Sur",
      "name_esus": "Carolina del Sur",
      "name_dede": "South Carolina",
      "links": [
        {
          "href": "countries/231",
          "rel": "countries",
          "type": "GET"
        }
      ]
    },
    {
      "type": "states",
      "id": 52,
      "country": 40,
      "code": "CA_SK",
      "name_enus": "Saskatchewan",
      "name_frfr": "Saskatchewan",
      "name_frca": "Saskatchewan",
      "name_ruru": "Саскачеван",
      "name_ptbr": "Saskatchewan",
      "name_plpl": "Saskatchewan",
      "name_itit": "Saskatchewan",
      "name_eses": "Saskatchewan",
      "name_esus": "Saskatchewan",
      "name_dede": "Saskatchewan",
      "links": [
        {
          "href": "countries/40",
          "rel": "countries",
          "type": "GET"
        }
      ]
    }
  ]
}

Using this API, you can fetch a list of states.

GET /webapi/states

Includes (States)

Example

curl -H 'Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6bUpqR29GY2Z3Z1Eycnh2aGl0dDpudXRjYWNoZTFAZ21haWwuY29tOkR5bmFjb20xMjM=' 
     -H 'api-version: 3' 
     -X GET https://apps.nutcache.com/webapi/states/12?includes=countries

The following entity types can be included in this payload type:

Type Description
countries The country associated with this state

Time Entries

A time entry is a recording of the amount of time a member spent on a specific task.

Using the API allows you to do the following with time entry data.

Attribute Type Description
billable_minutes number Billable time entry in minutes.
Available for projects that are billable (project.billing_method <> 0).
creation_date datetime Date the time entry was created.
creation_userprofile number Unique identifier for a member that originally created the time entry.
end_time datetime Date time that represents the end of the time entry.
Available if time tracking mode is set to Start/End time (organization.time_tracking_type = 1)).
id number Unique identifier.
invoice number Unique identifier for an invoice.
member number Unique identifier for a member.
minutes number Number of minutes logged.
note string Notes.
project number Unique identifier for a project.
project_service number Unique identifier for a project service.
start_time datetime Date time that represents the start of the time entry.
Available if time tracking mode is set to Start/End time (organization.time_tracking_type = 1)).
type time_entries Type of response.
working_date datetime Date time that represents the day of the time entry.

Viewing a time entry

Example

curl -H 'Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6ckpqR2ZGY2Z3Z1Eycnh2aGl0ZDphcGlkb2NzQGFwaWRvY3MuY29tOnBhc3N3b3Jk' 
     -H 'api-version: 3' 
     -H 'OrganizationGuid: 846E176E-7C4B-4BFD-A894-C98F2988927E' 
     -X GET https://apps.nutcache.com/webapi/time_entries/1

Response

{
  "time_entries": [
    {
      "type": "time_entries",
      "id": 201001,
      "billable_minutes": 0,
      "creation_date": "2018-03-06T22:01:09.25",
      "creation_userprofile": 2814,
      "working_date": "2018-03-07T00:00:00",
      "minutes": 480,
      "note": null,
      "project_service": 106963,
      "member": 9015,
      "project": 6641,
      "links": [
        {
          "href": "projects/6641",
          "rel": "projects",
          "type": "GET"
        },
        {
          "href": "project_services/106963",
          "rel": "project_services",
          "type": "GET"
        },
        {
          "href": "members/9015",
          "rel": "members",
          "type": "GET"
        },
        {
          "href": "time_entries/201001",
          "rel": "self",
          "type": "GET"
        }
      ],
      "invoice": null
    }
  ]
}

This API allows you to view the details of a time entry.

GET /webapi/time_entries/[id]

Parameter Description
id Unique identifier of the time entry.

List all time entries

Example

curl -H 'Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6ckpqR2ZGY2Z3Z1Eycnh2aGl0ZDphcGlkb2NzQGFwaWRvY3MuY29tOnBhc3N3b3Jk' 
     -H 'api-version: 3' 
     -H 'OrganizationGuid: 846E176E-7C4B-4BFD-A894-C98F2988927E' 
     -X GET https://apps.nutcache.com/webapi/time_entries

Response

{
  "links": [    
    {
      "href": "time_entries?limit=10&page=2",
      "rel": "navigation-next",
      "type": "GET"
    }
  ],
  "time_entries": [
    {
      "type": "time_entries",
      "id": 201001,
      "billable_minutes": 0,
      "creation_date": "2018-03-06T22:01:09.25",
      "creation_userprofile": null,
      "working_date": "2018-03-07T00:00:00",
      "minutes": 480,
      "note": null,
      "project_service": 106963,
      "member": 9015,
      "project": 6641,
      "links": [
        {
          "href": "projects/6641",
          "rel": "projects",
          "type": "GET"
        },
        {
          "href": "project_services/106963",
          "rel": "projectitems",
          "type": "GET"
        },
        {
          "href": "members/9015",
          "rel": "members",
          "type": "GET"
        },
        {
          "href": "time_entries/201001",
          "rel": "self",
          "type": "GET"
        }
      ],
      "invoice": null
    }
  ]
}

Using this API, you can fetch a list of time entries.

GET /webapi/time_entries

Includes (Time entries)

Example

curl -H 'Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6ckpqR2ZGY2Z3Z1Eycnh2aGl0ZDphcGlkb2NzQGFwaWRvY3MuY29tOnBhc3N3b3Jk' 
     -H 'api-version: 3' 
     -H 'OrganizationGuid: 846E176E-7C4B-4BFD-A894-C98F2988927E' 
     -X GET https://apps.nutcache.com/webapi/time_entries/1?includes=members,projects,project_services

The following entity types can be included in this payload type:

Type Description
invoices The invoice associated with this time entry.
members The member associated with this time entry.
organizations The organization containing this time entry.
projects The project associated with this time entry.
project_services The task associated with this time entry.

Creating a time entry

Example

curl -H 'Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6ckpqR2ZGY2Z3Z1Eycnh2aGl0ZDphcGlkb2NzQGFwaWRvY3MuY29tOnBhc3N3b3Jk' 
     -H 'api-version: 3'
     -H 'OrganizationGuid: 846E176E-7C4B-4BFD-A894-C98F2988927E'
     -X POST -d {"timeentries": [{"start_time":"2018-09-20T09:00", "end_time":"2018-09-20T21:45","note":"Modified from API 3",project_service":106972,"member":9015,"project":6645,"invoice":""}]} https://apps.nutcache.com/webapi/time_entries

This API allows time entries to be created.

POST /webapi/time_entries

Time entries created (working_date) inside an approved day/week have the option to notify administrators.

POST /webapi/time_entries?notify=true

Updating a time entry

Example

curl -H 'Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6ckpqR2ZGY2Z3Z1Eycnh2aGl0ZDphcGlkb2NzQGFwaWRvY3MuY29tOnBhc3N3b3Jk' 
     -H 'api-version: 3'
     -H 'OrganizationGuid: 846E176E-7C4B-4BFD-A894-C98F2988927E'
     -X PUT -d {"timeentries": [{"start_time":"2018-09-20T09:00", "end_time":"2018-09-20T21:45","note":"Modified from API 3",project_service":106972,"member":9015,"project":6645,"invoice":""}]} https://apps.nutcache.com/webapi/time_entries/1

This API allows existing time entries to be modified.

PUT /webapi/time_entries/[id]

Parameter Description
id Unique identifier of the time entry.

Time entries updated inside an approved day/week have the option to notify administrators.

PUT /webapi/time_entries/[id]?notify=true

Deleting a time entry

Example

curl -H 'Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6ckpqR2ZGY2Z3Z1Eycnh2aGl0ZDphcGlkb2NzQGFwaWRvY3MuY29tOnBhc3N3b3Jk' 
     -H 'api-version: 3'
     -H 'OrganizationGuid: 846E176E-7C4B-4BFD-A894-C98F2988927E'
     -X DELETE https://apps.nutcache.com/webapi/time_entries/1

DELETE /webapi/time_entries/[id]

Parameter Description
id Unique identifier of the time entry.

Time entries deleted inside an approved day/week have the option to notify administrators.

DELETE /webapi/time_entries/[id]?notify=true

Timers

A Nutcache timer is a stopwatch used to record time spent on a task.

Using the API allows you to do the following with timer data.

Attribute Type Description
email_reminder_sent boolean Set to True if a reminder is sent when a timer runs more than 24 hours.
id number Unique identifier.
max_end_time_utc datetime End time maximum value (UTC time)
member number Unique identifier for a member.
minutes number Minutes.
project number Unique identifier for a project.
project_service number Unique identifier for a project service.
status number Enum for the timer status:
0 = Started.
1 = Stopped.
2 = System stopped.
time_start_local datetime Timer start (local time).
time_start_utc datetime Timer start (UTC time).
type timers Type of response.

Viewing a timer

Example

curl -H "Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6ckpqR2ZGY2Z3Z1Eycnh2aGl0ZDphcGlkb2NzQGFwaWRvY3MuY29tOnBhc3N3b3Jk" 
     -H "api-version: 3" 
     -H "OrganizationGuid: 846E176E-7C4B-4BFD-A894-C98F2988927E" 
     -X GET https://apps.nutcache.com/webapi/timers/3546

Response

{
  "timers": [
    {
      "type": "timers",
      "id": 3546,
      "member": 9015,
      "time_start_local": "2018-09-07T11:55:00",
      "max_end_time_utc": "2018-09-08T04:00:04",
      "time_start_utc": "2018-09-07T15:55:47.377",
      "minutes": 0,
      "status": "1",
      "email_reminder_sent": false,
      "project": 7224,
      "links": [
        {
          "href": "projects/7224",
          "rel": "projects",
          "type": "GET"
        },
        {
          "href": "members/9015",
          "rel": "members",
          "type": "GET"
        },
        {
          "href": "timers/3546",
          "rel": "self",
          "type": "GET"
        }
      ],
      "project_service": null
    }
  ]
}

This API allows you to view the details of a timer.

GET /webapi/timers/[id]

Parameter Description
id Unique identifier of the timer.

List all timers

Example

curl -H "Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6ckpqR2ZGY2Z3Z1Eycnh2aGl0ZDphcGlkb2NzQGFwaWRvY3MuY29tOnBhc3N3b3Jk" 
     -H "api-version: 3" 
     -H "OrganizationGuid: 846E176E-7C4B-4BFD-A894-C98F2988927E" 
     -X GET https://apps.nutcache.com/webapi/timers

Response

{
  "links": [
    {
      "href": "timers?limit=10&page=2",
      "rel": "navigation-next",
      "type": "GET"
    }
  ],
  "timers": [
    {
      "type": "timers",
      "id": 3546,
      "guid": "{aa8995ef-59e9-4173-ad5c-b923b46e20d7}",
      "member": 9015,
      "time_start_local": "2018-09-07T11:55:00",
      "max_end_time_utc": "2018-09-08T04:00:04",
      "time_start_utc": "2018-09-07T15:55:47.377",
      "minutes": 0,
      "status": "1",
      "email_reminder_sent": false,
      "project": 7224,
      "links": [
        {
          "href": "projects/7224",
          "rel": "projects",
          "type": "GET"
        },
        {
          "href": "members/9015",
          "rel": "members",
          "type": "GET"
        },
        {
          "href": "timers/3546",
          "rel": "self",
          "type": "GET"
        }
      ],
      "project_service": null
    }
  ]
}

Using this API, you can fetch a list of timers.

GET /webapi/timers

Includes (Timers)

Example

curl -H "Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6ckpqR2ZGY2Z3Z1Eycnh2aGl0ZDphcGlkb2NzQGFwaWRvY3MuY29tOnBhc3N3b3Jk" 
     -H "api-version: 3" 
     -H "OrganizationGuid: 846E176E-7C4B-4BFD-A894-C98F2988927E" 
     -X GET https://apps.nutcache.com/webapi/timers/3546?includes=projects,members

The following entity types can be included in this payload type:

Type Description
members The member associated with the timer.
projects The project associated with the timer.
project_services The service associated with the timer.
sprint_stories The project board card associated with the timer.

Search

Filtered Searches

Filtered searches can be used to find entities that match specific search criteria.

Usage

Filter Construct

{
  "filter_rules": [
    {
      "property": "_name_",
      "operator": "_operator_",
      "value": "_value_"
    }
  ]
}

POST _entity_/filtered

Filters can be combined together as follows:

{
  "filter_rules": [
    {
      "property": "_name_",
      "operator": "_operator_",
      "value": "_value_"
    },
    {
      "property": "_name_",
      "operator": "_operator_",
      "value": "_value_"
    }
  ]
}

Example

curl -H 'Authorization: nut-basic YVl6T1JtbkdpMHhwaXhCdTQ5b3l6ckpqR2ZGY2Z3Z1Eycnh2aGl0ZDphcGlkb2NzQGFwaWRvY3MuY29tOnBhc3N3b3Jk' 
     -H 'Content-Type:application/json' 
     -H 'api-version: 3' 
     -H 'OrganizationGuid: 846E176E-7C4B-4BFD-A894-C98F2988927E' 
     -X POST https://apps.nutcache.com/webapi/customers/filtered 
     -d '{"filter_rules": [{"property": "name","operator": "ct","value": "Test"}]}'

Filter Operators

Operator Description
eq Equals.
neq Not Equals.
gt Greater Than.
lt Less Than.
gte Greater Than or Equals.
lte Less Than or Equals.
ct Contains.
sw Starts With.
ew Ends With.

Sorting

Sorting Construct

 "sorting_rules": [
    {
      "property": "description",
      "direction": "desc"
    },
    {
      "property": "code",
      "direction": "asc"
    }
  ]

Results from filtered searches can be sorted using filtered actions with sorting rules.

Sort Directions

Direction Supported Terms
Ascending asc, ascending.
Descending desc, descending.

Errors

API requests that result in errors will return an appropriate HTTP code to help you identify the type of error and fix it. You can use the table below to understand what each code means.

Code Text Description
400 Client or Validation Error This indicates that the request is not in the correct format.
401 Access Denied This indicates that the Authorization header is either missing or incorrect. You can learn more about the Authorization header here.
403 Client or Validation Error This indicates that the user whose credentials were used in making this request was not authorized to perform this API call.
404 Requested Resource not Found This code is returned when the request contains invalid ID/Nutcache domain in the URL or an invalid URL itself. For example, an API call to retrieve a project with an invalid ID will return a HTTP 404 status code to let you know that no such project exists.
429 Too Many Requests This code appears when the user has exceeded the API rate limit. In Nutcache, this limit is set to 20000 API requests per day per API key.
500 Unexpected Server Error This indicates an error on Nutcache's side. Please email us at support@nutcache.com with any relevant information. We will reach out to you and fix this ASAP.
cUrl