Customers

Endpoint: https://api.oneup.com/v1/customers

JSON Format

Customers are represented as JSON objects which have the following keys:

Field Name Type Mandatory Read-only Description
id integer no yes Automatically assigned when creating customers
type integer yes no The type of the customer
1: Company
2: Individual
status integer no no 1: Customer (default)
2: Lead
full_name string no yes The full name of this customer (automatically generated).
address Address no no The main address of the customer
shipping_address Address no no The shipping address of the customer
phone_number string no no The phone number of this customer. 64 characters max.
email string no no The Email address of this customer. 255 characters max.
website string no no The URL of the customer's website. 255 characters max.
contacts array[Contact] no no An array containing the contacts of the customer
payment_terms Payment Terms no no The Payment terms object
by default, Due on receipt will be selected.
currency_iso_code string no no The ISO Code of one of your Currencies
by default, the domain currency will be selected. 4 characters max.
sales_tax Tax no no A Tax object
user_code string no no The number assigned to this customer (i.e. CUS-002). If you don't specify a customer number, it will be automatically generated. 64 characters max.
opt_in_email boolean no no Opt-in to Emails. Default: false
notes string no no A note about this customer
assigned_to Object no no The employee object. The authenticated user by default
employee_count integer no no The company's employee count
price_family Object no no The price family applied to this customer
taxpayer_id string no no The customer's taxpayer id
industry string no no The customer's industry
incorporation_status string no no The customer's incorporation status
rating string no no The lead's rating

Company only

If your customer is a company, the JSON object will have the following keys:
Field Name Type Mandatory Read-only Description
company_name string yes no The name of the company. 255 characters max.

Individual only

If your customer is an individual, the JSON object will have the following keys:
Field Name Type Mandatory Read-only Description
first_name string no no The First Name of the customer. 255 characters max.
last_name string yes no The Last Name of the customer. 255 characters max.
middle_name string no no The Middle Name of the customer. 255 characters max.

JSON Example

{
    "id": 146800,
    "type": 1,
    "status": 1,
    "full_name": "OneUp",
    "address": {
        "street_line1": "567 Sutter St.",
        "street_line2": "",
        "street_line3": "",
        "postal_code": "94102",
        "city": "San Francisco",
        "country": "United States",
        "locality": "California",
        "short_locality": "CA",
        "full_address": "567 Sutter St. San Francisco CA 94102 United States"
    },
    "shipping_address": {
        "street_line1": "567 Sutter St.",
        "street_line2": "",
        "street_line3": "",
        "postal_code": "94102",
        "city": "San Francisco",
        "country": "United States",
        "locality": "California",
        "short_locality": "CA",
        "full_address": "567 Sutter St. San Francisco CA 94102 United States"
    },
    "phone_number": "(415) 779-6536",
    "email": "support@oneup.com",
    "website": "www.oneup.com",
    "payment_terms": {
        "id": 1,
        "name": "Due on receipt"
    },
    "currency_iso_code": "USD",
    "sales_tax": {
        "id": 1,
        "name": "0.0% Example of Sales Tax (Collected)",
        "rate": 0.0
    },
    "user_code": "CUS-018",
    "opt_in_email": false,
    "notes": "- OneUp -\nRun your business in the Cloud",
    "assigned_to": {
        "id": 2,
        "first_name": "John",
        "last_name": "Smith",
        "user_code": "EMP-002"
    },
    "company_name": "OneUp",
    "employee_count": 1,
    "taxpayer_id": "123456789",
    "price_family": {
        "id": 1,
        "name": "Price Family"
    },
    "industry": "Apparel",
    "incorporation_status": "C-Corporation",
    "rating": "Cold"
}

Available Methods

HTTP Verb Action
GET Retrieve a resource, you have to specify an id
PUT Update a resource, you have to specify an id
DELETE Delete a resource, you have to specify an id
POST Create a resource
GET Retrieve the list of resources

Vendors

Endpoint: https://api.oneup.com/v1/vendors

JSON Format

Vendors are represented as JSON objects which have the following keys:

Field Name Type Mandatory Read-only Description
id integer no yes Automatically assigned when creating customers
type integer yes no The type of the vendor
1: Company
2: Individual
full_name string no yes The full name of this customer (automatically generated)
address Address no no The main address of the vendor
phone_number string no no The phone number of this vendor. 64 characters max.
email string no no The Email address of this vendor. 255 characters max.
website string no no The URL of the vendor's website. 255 characters max.
contacts array[Contact] no no An array containing the contacts of the vendor
payment_terms_id integer no no The ID of the Payment terms
by default, Due on receipt will be selected.
currency_iso_code string no no The ISO Code of one of your Currencies
by default, the domain currency will be selected. 4 characters max.
user_code string no no The number assigned to this vendor (i.e. SUP-002). If you don't specify a vendor number, it will be automatically generated. 64 characters max.
note no no A note about this vendor
taxpayer_id_number string no no The Taxpayer ID Number

Company only

If your vendor is a company, the JSON object will have the following keys:
Field Name Type Mandatory Read-only Description
company_name string yes no The name of the company. 255 characters max.

Individual only

If your vendor is an individual, the JSON object will have the following keys:
Field Name Type Mandatory Read-only Description
first_name string no no The First Name of the vendor. 255 characters max.
last_name string yes no The Last Name of the vendor. 255 characters max.
middle_name string no no The Middle Name of the vendor. 255 characters max.

JSON Example

{
  "id": 132,
  "type": 1,
  "full_name": "Regular Vendor",
  "address": {
    "street_line1": "Regular street",
    "street_line2": "Block G",
    "street_line3": "Floor 5",
    "postal_code": "77 837",
    "city": "San Francisco",
    "country": "USA",
    "locality": "California",
    "short_locality": "CA",
    "full_address": "Regular street Block G Floor 5 San Francisco CA 77 837 USA"
  },
  "phone_number": "555 7890 888",
  "email": "regular.vendor@gmail.com",
  "website": "regularvendor.com",
  "contacts": [
    {
      "id": 65,
      "first_name": "Regular",
      "last_name": "Vendor",
      "full_name": "Regular Vendor",
      "cell_number": "",
      "work_phone": "888 7654 333",
      "home_phone": "",
      "email": "r.vendor@mail.com",
      "address": {
        "street_line1": "",
        "street_line2": "",
        "street_line3": "",
        "postal_code": "",
        "city": "",
        "country": "",
        "locality": "N/A",
        "short_locality": "N/A",
        "full_address": ""
      },
      "note": "This contact is pretty regular."
    }
  ],
  "currency": "USD",
  "payment_terms_id": 1,
  "taxpayer_id_number": "SE OIU 90",
  "user_code": "SUP-002",
  "note": "This vendor is pretty regular.",
  "company_name": "Regular Vendor"
}

Available Methods

HTTP Verb Action
GET Retrieve a resource, you have to specify an id
PUT Update a resource, you have to specify an id
DELETE Delete a resource, you have to specify an id
POST Create a resource
GET Retrieve the list of resources

Products and Services

Endpoint: https://api.oneup.com/v1/items

JSON Format

Products and Services are represented as JSON objects which have the following keys:

Field Name Type Mandatory Read-only Description
id integer no yes Automatically assigned when creating Transactions
type integer yes no The type
1: Service
2: Product
name string yes no The name. 255 characters max.
unit_id integer no no The ID of the Unit
Default:
Service: Day
Product: Piece
sales_price double no no The Sales Price, 0.0 by default
item_number string no no A unique user-facing id (i.e. ITM-012) If you don't specify a product number, it will be automatically generated. 64 characters max.
description string no no A description of the product or the service
family_id integer no no IDs from Item's Families
Miscellaneous, by default
private_note string no no A private note about the product or the service

Products only

Field Name Type Mandatory Read-only Description
purchase_price double no no The Purchase Price of the product. 0.0 by default
net_weight double no no The Net Weight of the product. 0.0 by default
width double no no The Width of the product. 0.0 by default
length double no no The Length of the product. 0.0 by default
height double no no The Height of the product. 0.0 by default
dimension_unit_id integer no no The id of the Dimension Unit of the product. Meter by default

JSON Example

{
  "id": 230071,
  "type": 2,
  "name": "Nintendo Wii",
  "unit_id": 2,
  "sales_price": 199.0,
  "purchase_price": 159.0,
  "item_number": "ITM-012",
  "description": "A video game console.",
  "family_id": 3,
  "private_note": "I got one !",
  "net_weight": 1.740,
  "width": 0.157,
  "length": 0.215,
  "height": 0.440,
  "dimension_unit_id": 3
}

Available Methods

HTTP Verb Action
GET Retrieve a resource, you have to specify an id
PUT Update a resource, you have to specify an id
DELETE Delete a resource, you have to specify an id
POST Create a resource
GET Retrieve the list of resources

Products and Services Families

Endpoint: https://api.oneup.com/v1/item_families

JSON Format

Products and Services Families are represented as JSON objects which have the following keys:

Field Name Type Mandatory Read-only Description
id integer no yes Automatically assigned when creating Families
name string yes no The Family Name. 64 characters max.
code yes no The Short Code of the Family. Automatically generated. 64 characters max.

JSON Example

{
  "id": 4,
  "name": "Video Game",
  "code": "FAM-007"
}

Available Methods

HTTP Verb Action
GET Retrieve a resource, you have to specify an id
PUT Update a resource, you have to specify an id
DELETE Delete a resource, you have to specify an id
POST Create a resource
GET Retrieve the list of resources

Projects

Endpoint: https://api.oneup.com/v1/projects

JSON Format

Projects are represented as JSON objects which have the following keys:

Field Name Type Mandatory Read-only Description
id integer no yes Automatically assigned when creating projects
name string yes no The Project Name. 128 characters max.
description no no The Project Description

JSON Example

{
    "id": 32,
    "name": "Project X",
    "description": "A wonderful project !\nLet's make money."
}

Available Methods

HTTP Verb Action
GET Retrieve a resource, you have to specify an id
PUT Update a resource, you have to specify an id
DELETE Delete a resource, you have to specify an id
POST Create a resource
GET Retrieve the list of resources

Project Tasks

Endpoint: https://api.oneup.com/v1/project_tasks

JSON Format

Project Tasks are represented as JSON objects which have the following keys:

Field Name Type Description
id integer Automatically assigned when creating a task
name string The task name.
notes string The task notes.
status string "done" if the task is completed, "todo" otherwise.
due_date date Date on which this task is due, or null if the task has no due date.
done_date date Date on which this task was completed, or null if the task has no done date.
time_spent double The time spent to complete this task, or null if the task is not done yet.
assigned_to object Employee to which this task is assigned, or null if the task is unassigned.
customer object Compact representation of the customer linked to this task, or null if no customer linked.
contact object Compact representation of the contact linked to this task, or null if no contact linked.
project object Compact representation of the project linked to this task, or null if no project linked.
service_to_bill object Compact representation of the service to bill linked to this task, or null if no service linked.

JSON Example

 {
  "id": 6,
  "name": "Buy supplies",
  "notes": "Let's buy the supplies.",
  "status": "todo",
  "due_date": "2016-03-17",
  "done_date": null,
  "time_spent": null,
  "assigned_to": {
    "id": 120,
    "first_name": "John",
    "last_name": "Doe",
    "user_code": "EMP-005"
  },
  "customer": {
    "id": 517001,
    "name": "Smith Inc",
    "user_code": "CUS-1108"
  },
  "contact": {
    "id": 353659,
    "name": "Jane Smith",
    "user_code": "CCUS-1422"
  },
  "project": {
    "id": 2,
    "name": "Project 2"
  }, 
  "service_to_bill": {
    "id": 6252,
    "name": "Service",
    "user_code": "PS-004"
  }
} 

Available Methods

HTTP Verb Action
GET Retrieve a resource, you have to specify an id
GET Retrieve the list of resources

Opportunity Tasks

Endpoint: https://api.oneup.com/v1/opportunity_tasks

JSON Format

Opportunity Tasks are represented as JSON objects which have the following keys:

Field Name Type Description
id integer Automatically assigned when creating a task
name string The task name.
notes string The task notes.
status string "done" if the task is completed, "todo" otherwise.
due_date date Date on which this task is due, or null if the task has no due date.
done_date date Date on which this task was completed, or null if the task has no done date.
time_spent double The time spent to complete this task, or null if the task is not done yet.
assigned_to object Employee to which this task is assigned, or null if the task is unassigned.
customer object Compact representation of the customer linked to this task, or null if no customer linked.
contact object Compact representation of the contact linked to this task, or null if no contact linked.
opportunity object Compact representation of the opportunity linked to this task, or null if no opportunity linked.

JSON Example

 {
  "id": 6,
  "name": "Buy supplies",
  "notes": "Let's buy the supplies.",
  "status": "todo",
  "due_date": "2016-03-17",
  "done_date": null,
  "time_spent": null,
  "assigned_to": {
    "id": 120,
    "first_name": "John",
    "last_name": "Doe",
    "user_code": "EMP-005"
  },
  "customer": {
    "id": 517001,
    "name": "Smith Inc",
    "user_code": "CUS-1108"
  },
  "contact": {
    "id": 353659,
    "name": "Jane Smith",
    "user_code": "CCUS-1422"
  },
  "opportunity": {
    "id": 2,
    "name": "Opportunity 2"
  }
} 

Available Methods

HTTP Verb Action
GET Retrieve a resource, you have to specify an id
GET Retrieve the list of resources

Sales Orders

Endpoint: https://api.oneup.com/v1/sales_orders

JSON Format

Sales orders are represented as JSON objects which have the following keys:

Field Name Type Mandatory Read-only Description
id integer no yes Automatically assigned.
customer_id integer yes no Id of the Customer.
billing_contact_id integer no no Id of the Contact to bill.
Should belong to that order's Customer.
billing_address Address no yes The billing address. The Contact address if any, the Customer one otherwise.
user_code string no no The number assigned to this sales order (i.e. SO-002). If you don't specify an order number, it will be automatically generated.
64 characters max.
po_number string no no The Customer own Order Reference.
64 characters max.
date date no no The date that will be printed.
Format: yyyy-MM-dd (e.g. 2013-06-26)
Default: date of the day.
tax_id integer no no US only.
Id of the Tax to apply on that order.
currency_iso_code string no no The ISO code of the currency (ISO 4217). 4 characters max.
That currency should have been previously added into your company settings.
Default: your company's currency.
reduce_rate double no no The reduce rate (%) to apply. From 0 to 100.
Default: 0.00
order_lines array[Order Line] no no An array containing the order lines of the order.
public_note string no no Comment that will be printed on the final document.
shipping_date date no no The date before which the goods should be delivered, if any.
Format: yyyy-MM-dd (e.g. 2013-06-26)
shipping_contact_id integer no no Id of the Contact the goods should be shipped to, if different than the Customer.
Could be any Contact from any Customer.
shipping_address Address no yes The shipping address. The shpping Contact address if any, the Customer one otherwise.
payment_terms_id integer no no Id of the Payment Term to apply once that order will be billed.
project_id integer no no Id of the Project related to that order, if any.
employee_id integer no no Id of the Employee assigned to that order.
Default: the authenticated user.
private_note string no no A private note that won't be printed.
subtotal double no yes Total before taxes and reduce. Based on the content of the order lines.
reduce_amount double no yes Amount of the reduce, based on the subtotal and reduce rate.
tax_amount double no yes Overall tax amount. Inludes all taxes, discounts and reduce.
total double no yes The final total the customer needs to pay. All include (taxes, discounts, reduce).
delivery_status integer no yes The delivery status, among :
1: Not Delivered (default)
2: Partially Delivered
3: Delivered
invoice_status integer no yes The invoice status, among :
1: Not invoiced (default)
2: Invoiced
3: Cancelled

JSON Example

That example describe a US sales order.

{
  "id": 8,
  "customer_id": 2,
  "billing_contact_id": 1,
  "billing_address": {
    "street_line1": "57 Benjamin Franklin Street",
    "street_line2": "",
    "street_line3": "",
    "postal_code": "",
    "city": "San Francisco",
    "country": "USA",
    "locality": "California",
    "short_locality": "CA",
    "full_address": "57 Benjamin Franklin Street San Francisco CA USA"
  },
  "user_code": "CORD-006",
  "po_number": "WC-SO-32492-XCT",
  "date": "2014-05-07",
  "tax_id": 2,
  "currency_iso_code": "USD",
  "reduce_rate": 3.5,
  "order_lines": [
    {
      "id": 66,
      "item_id": 1,
      "description": "",
      "quantity": 50.0,
      "unit_price_wt": 15.0,
      "discount_rate": 0.0,
      "tax_id": 2,
      "is_taxable": true,
      "total": 750.0
    },
    {
      "id": 67,
      "item_id": 3,
      "description": "10 random stickers for WC2014 album.",
      "quantity": 100.0,
      "unit_price_wt": 1.5,
      "discount_rate": 5.0,
      "tax_id": 2,
      "is_taxable": true,
      "total": 142.5
    },
    {
      "id": 68,
      "item_id": 2,
      "description": "A beautiful stickers album about Soccer.\n- Limited Edition -",
      "quantity": 20.0,
      "unit_price_wt": 9.99,
      "discount_rate": 0.0,
      "tax_id": 0,
      "is_taxable": false,
      "total": 199.8
    }
  ],
  "public_note": "All in one rhythm - Juntos num só ritmo",
  "shipping_date": "2014-06-12",
  "shipping_address": {
    "street_line1": "Rue Henri Delaunay",
    "street_line2": "",
    "street_line3": "",
    "postal_code": "93210",
    "city": "Saint-Denis",
    "country": "France",
    "locality": "N/A",
    "short_locality": "N/A",
    "full_address": "Rue Henri Delaunay Saint-Denis 93210 France"
  },
  "payment_terms_id": 4,
  "employee_id": 1,
  "private_note": "Needs to be ready for the opening !",
  "subtotal": 1092.3,
  "reduce_amount": 38.23,
  "tax_amount": 86.13,
  "total": 1140.2,
  "delivery_status": 1,
  "invoice_status": 1
}

Available Methods

HTTP Verb Action
GET Retrieve a resource, you have to specify an id
PUT Update a resource, you have to specify an id
DELETE Delete a resource, you have to specify an id
POST Create a resource
GET Retrieve the list of resources

Invoices

Endpoint: https://api.oneup.com/v1/invoices

JSON Format

Invoices are represented as JSON objects which have the following keys:

Field Name Type Mandatory Read-only Description
id integer no yes Automatically assigned.
customer_id integer yes no Id of the Customer.
billing_contact_id integer no no Id of the Contact to bill.
Should belong to that invoice's Customer.
billing_address Address no yes The billing address. The Contact address if any, the Customer one otherwise.
user_code string no no The number assigned to that invoice (i.e. INV-002). If you don't specify an order number, it will be automatically generated.
64 characters max.
po_number string no no The Customer own Order Reference.
64 characters max.
date date no no The date that will be printed.
Format: yyyy-MM-dd (e.g. 2013-06-26)
Default: date of the day.
tax_id integer no no US only.
Id of the Tax to apply on that invoice.
currency_iso_code string no no The ISO code of the currency (ISO 4217). 4 characters max.
That currency should have been previously added into your company settings.
Default: your company's currency.
reduce_rate double no no The reduce rate (%) to apply. From 0 to 100.
Default: 0.00
order_lines array[Order Line] no no An array containing the order lines of the invoice.
public_note string no no Comment that will be printed on the final document.
shipping_date date no no The date before which the goods should be delivered, if any.
Format: yyyy-MM-dd (e.g. 2013-06-26)
shipping_contact_id integer no no Id of the Contact the goods should be shipped to, if different than the Customer.
Could be any Contact from any Customer.
shipping_address Address no yes The shipping address. The shpping Contact address if any, the Customer one otherwise.
payment_terms_id integer no no Id of the Payment Term to apply on that invoice. Will be used as a template to generate Settlements.
project_id integer no no Id of the Project related to that invoice, if any.
employee_id integer no no Id of the Employee assigned to that order.
Default: the authenticated user.
private_note string no no A private note that won't be printed.
subtotal double no yes Total before taxes and reduce. Based on the content of the order lines.
reduce_amount double no yes Amount of the reduce, based on the subtotal and reduce rate.
tax_amount double no yes Overall tax amount. Inludes all taxes, discounts and reduce.
total double no yes The final total the customer needs to pay. All include (taxes, discounts, reduce).
paid double no yes Total of the payments made on that invoice.
unpaid double no yes Remaining amount to be paid.
delivery_status integer no yes The delivery status, among :
1: Not Delivered (default)
2: Partially Delivered
3: Delivered
payments_id array[integer] no yes Array of Ids of Payments made on that invoice.

JSON Example

That example describe a US invoice.

{
  "id": 19,
  "customer_id": 2,
  "billing_contact_id": 1,
  "billing_address": {
    "street_line1": "57 Benjamin Franklin Street",
    "street_line2": "",
    "street_line3": "",
    "postal_code": "",
    "city": "San Francisco",
    "country": "USA",
    "locality": "California",
    "short_locality": "CA",
    "full_address": "57 Benjamin Franklin Street San Francisco CA USA"
  },
  "user_code": "CINV-015",
  "po_number": "WC-SO-32492-XCT",
  "date": "2014-05-07",
  "tax_id": 2,
  "currency_iso_code": "USD",
  "reduce_rate": 3.5,
  "order_lines": [
    {
      "id": 69,
      "item_id": 1,
      "description": "",
      "quantity": 50.0,
      "unit_price_wt": 15.0,
      "discount_rate": 0.0,
      "tax_id": 2,
      "is_taxable": true,
      "total": 750.0
    },
    {
      "id": 70,
      "item_id": 3,
      "description": "10 random stickers for WC2014 album.",
      "quantity": 100.0,
      "unit_price_wt": 1.5,
      "discount_rate": 5.0,
      "tax_id": 2,
      "is_taxable": true,
      "total": 142.5
    },
    {
      "id": 71,
      "item_id": 2,
      "description": "A beautiful stickers album about Soccer.\n- Limited Edition -",
      "quantity": 20.0,
      "unit_price_wt": 9.99,
      "discount_rate": 0.0,
      "tax_id": 0,
      "is_taxable": false,
      "total": 199.8
    }
  ],
  "public_note": "All in one rhythm - Juntos num só ritmo",
  "shipping_address": {
    "street_line1": "Rue Henri Delaunay",
    "street_line2": "",
    "street_line3": "",
    "postal_code": "93210",
    "city": "Saint-Denis",
    "country": "France",
    "locality": "N/A",
    "short_locality": "N/A",
    "full_address": "Rue Henri Delaunay Saint-Denis 93210 France"
  },
  "payment_terms_id": 4,
  "employee_id": 1,
  "private_note": "Needs to be ready for the opening !",
  "subtotal": 1092.3,
  "reduce_amount": 38.23,
  "tax_amount": 86.13,
  "total": 1140.2,
  "paid": 770.1,
  "unpaid": 370.1,
  "delivery_status": 1,
  "payments_id": [
    32,
    33
  ]
}

Available Methods

HTTP Verb Action
GET Retrieve a resource, you have to specify an id
PUT Update a resource, you have to specify an id
DELETE Delete a resource, you have to specify an id
POST Create a resource
GET Retrieve the list of resources

Payments

Endpoint: https://api.oneup.com/v1/payments

Payment creation is restraint to Invoice's payments into the API. You have to provide an invoice_id while performing a POST request.
That new payment will be applied on the first open settlement of that invoice. If all settlements are paid, an error message will be returned and the payment won't be created.
Also, that new payment currency will be determined by the invoice's one.

Unlike creation, GET requests are not restraint to invoice's payments only and returns any kind of payments.

JSON Format

Payments are represented as JSON objects which have the following keys:

Field Name Type Mandatory Read-only Description
id integer no yes Automatically assigned when creating Payment
user_code string no yes The number that was automatically assigned to this payment (i.e. IPAY-002).
invoice_id integer yes yes Id of the Invoice that payment is about, if any.
date date no yes The date the payment has occured.
Format: yyyy-MM-dd (e.g. 2013-06-26)
Default: date of the day.
amount double yes yes Amount of the payment.
Should not be 0.00
currency_iso_code string no yes The ISO code of that payment currency (ISO 4217).
payment_method_id integer no yes Id of the Payment method.
Default: the one of the settlement that payment has been applied.
bank_reference string no yes A bank reference label that can freely be assigned. Could be a bank statement reference, a PayPal ID, etc...
bank_id integer no yes Id of the bank account that payment was made on.
That bank account currency should match the payment one.
Default: no Bank. Use the application to perform the bank deposit later on.

JSON Example

{
  "id": 25,
  "user_code": "IPAY-025",
  "invoice_id": 14,
  "date": "2014-07-25",
  "amount": 330.0,
  "currency_iso_code": "USD",
  "payment_method_id": 1,
  "bank_reference": "BK-XCT-094843904 PAY",
  "bank_id": 5
}

Available Methods

HTTP Verb Action
GET Retrieve a resource, you have to specify an id
DELETE Delete a resource, you have to specify an id
POST Create a resource
Restraint to invoice's payments only
GET Retrieve the list of resources

Accounting Transactions

Endpoint: https://api.oneup.com/v1/transactions

Accounting Transactions that have been generated by the system are only editable to some extends.
Only few fields, like external_id or lettering remain editable. Also, you cannot add or remove entries, edit amounts or change the date or piece_number. In order to do that, you have to edit the document that have generated the transaction.

Still, you can lock any entries to ensure that it won't be modified at all, but be carefull: once locked, an entry cannot be unlocked.

JSON Format

Accounting Transactions are represented as JSON objects which have the following keys:

Field Name Type Mandatory Read-only Description
id integer no yes Automatically assigned when creating Transactions.
external_id string no no Use primilary for Sync.
transaction_code integer no no Automatically generated
status string no yes The status of the transaction, among "Realized", "Forecast" and "Closed".

It's a read only field, transaction created through the API are Realized only.
date date no no Today by default.
Format: yyyy-MM-dd (e.g. 2013-06-26)

Not editable on transactions that have been generated by the system.
journal_id DEPRECATED integer no no Deprecated. See journal.
journal Journal no no The recording journal
5: Miscellaneous Operations is selected by default

Not editable on transactions that have been generated by the system.
piece_number string yes no A unique user-facing id of the document linked to this transaction. 64 characters max.

Not editable on transactions that have been generated by the system.
currency_iso_code string no yes The ISO code of the currency (ISO 4217). 4 characters max.
Default: your company's currency.

Not editable on transactions that have been generated by the system.

When creating new transactions, only default currency is allowed.
entries array[Entry] yes no The list of the transaction's entries. The entries must be balanced

You cannot add or remove entries on transactions that have been generated by the system.

Transaction Entry Format

Field Name Type Mandatory Read-only Description
id integer no yes Automatically assigned when creating Entries.
label string no no The description of the Entry. 128 characters max.
amount double yes no The amount of the Entry. Positive, will be rounded to two decimal places

Not editable on transactions that have been generated by the system.
way string yes no Defines if the amount is a Debit or a Credit
"debit" or "credit"

Not editable on transactions that have been generated by the system.
account_id integer yes no The id of the accounting account where isFamily = false only

Not editable on transactions that have been generated by the system.
account_label string no yes number and label of the accounting account
lettering string no no The lettering of this entry. 64 characters max.
locked boolean no no locked entries are not editable at all.
Once turned to 'true', it cannot be set back to 'false'.

JSON Example

{
  "id": 509878,
  "external_id": "EXT-API-079",
  "transaction_code": 1639,
  "status": "Realized",
  "date": "2014-01-31",
  "journal": {
    "id": 32,
    "name": "Journal name",
    "code": "JN"
  },
  "piece_number": "CINV-237",
  "currency_ico_code": "USD",
  "entries": [
    {
      "id": 1187484,
      "label": "Invoice Payment",
      "amount": 17578.65,
      "way": "debit",
      "account_id": 21,
      "account_label": "11100  ( Accounts Receivable - Trade )",
      "lettering": "CINV-237",
      "locked": false
    },
    {
      "id": 1187485,
      "label": "Invoice Payment - Before taxes",
      "amount": 16238.92,
      "way": "credit",
      "account_id": 85,
      "account_label": "40150  ( Sales - Miscellaneous )",
      "locked": false
    },
    {
      "id": 1187486,
      "label": "Invoice Payment - Taxes",
      "amount": 1339.73,
      "way": "credit",
      "account_id": 57,
      "account_label": "21100  ( Sales Tax Payable )",
      "locked": false
    }
  ]
}

Available Methods

HTTP Verb Action
GET Retrieve a resource, you have to specify an id
PUT Update a resource, you have to specify an id
DELETE Delete a resource, you have to specify an id
POST Create a resource
GET Retrieve the list of resources

Accounting journals

Endpoint: https://api.oneup.com/v1/journals

JSON Format

Journals are represented as JSON objects which have the following keys:

Field Name Type Mandatory Read-only Description
id integer no yes Automatically assigned when creating journals
name string yes no The journal name. 64 characters max.
code string yes no The journal name's abbreviation. 64 characters max.

JSON Example

{
    "id": 32,
    "name": "Journal name",
    "code": "JN"
}

Available Methods

HTTP Verb Action
GET Retrieve a resource, you have to specify an id
PUT Update a resource, you have to specify an id
DELETE Delete a resource, you have to specify an id
POST Create a resource
GET Retrieve the list of resources

Accounts

Endpoint: https://api.oneup.com/v1/accounts

JSON Format

Accounts are represented as JSON objects which have the following keys:

Field Name Type Mandatory Read-only Description
id integer no yes Automatically assigned
number string yes no The Number of this account. 64 characters max.
name string yes no The Name of this account. 128 characters max.
is_family boolean yes yes Is this account a family account.
family_id integer yes no Code of this account's family

JSON Example

{
    "id": 100,
    "number": "56100",
    "name": "Freight Charges",
    "is_family": false,
    "family_id": 13
}

Available Methods

HTTP Verb Action
GET Retrieve a resource, you have to specify an id
PUT Update a resource, you have to specify an id
DELETE Delete a resource, you have to specify an id
POST Create a resource
GET Retrieve the list of resources

Bank

Endpoint: https://api.oneup.com/v1/bank_accounts

JSON Format

Bank accounts are represented as JSON objects which have the following keys:

Field Name Type Mandatory Read-only Description
id integer no yes Automatically assigned.
account_number string no no The account number of the bank account.
name string yes no The way that bank account will appear in OneUp.
currency string no no The ISO Code of one of your Currencies
by default, the domain currency will be selected. 4 characters max.
linked_to_provider boolean no no Does this account come from an external provider.
bank_balance double no no The current balance of your bank account.
accounting_bank_balance double no no The current balance of your bank account, according to the OneUp accounting.
bank_balance_date date no no The date the bank balance has been recorded.
Format: yyyy-MM-dd (e.g. 2013-06-26)

JSON Example

{
  "id": 2769,
  "account_number": "748-94288-928",
  "name": "Bank of the West",
  "currency": "USD",
  "linked_to_provider": false,
  "bank_balance": 32487.09,
  "accounting_bank_balance": 59573.90,
  "bank_balance_date": "2015-02-20"
}

Available Methods

HTTP Verb Action
GET Retrieve a resource, you have to specify an id
PUT Update a resource, you have to specify an id
DELETE Delete a resource, you have to specify an id
POST Create a resource
GET Retrieve the list of resources

Bank Entries

Endpoint: https://api.oneup.com/v1/bank_entries

This API doesn't handle PUT requests.

JSON Format

Bank entries are represented as JSON objects which have the following keys:

Field Name Type Mandatory Read-only Description
id integer no yes Automatically assigned.
external_id string no yes Use primilary for Sync.
bank_account_id integer yes yes Code of the Bank Account that entry belongs to.
posted_date date yes yes The date that entry was posted.
Format: yyyy-MM-dd (e.g. 2013-06-26)
transaction_date date yes yes The date the bank transaction was actually performed.
Format: yyyy-MM-dd (e.g. 2013-06-26)
amount double yes yes Amount of the bank transaction. Use negative amount for debit.
Should not be 0.00
currency_iso_code string no yes The ISO Code of the bank account.
description string yes yes Short description.
payment_method_id integer no yes Code of the payment method.
Default: 1 (check)

JSON Example

{
  "id": 353,
  "external_id": "EXT-API-093",
  "bank_account_id": 4,
  "posted_date": "2014-05-05",
  "transaction_date": "2014-06-12",
  "amount": -133.94,
  "currency_iso_code": "USD",
  "description": "Walmart - Credit card payment",
  "payment_method_id": 2
}

Available Methods

HTTP Verb Action
GET Retrieve a resource, you have to specify an id
DELETE Delete a resource, you have to specify an id
POST Create a resource
GET Retrieve the list of resources

Payment Terms

Endpoint: https://api.oneup.com/v1/payment_terms

This API is read only.

JSON Format

Payment Terms are represented as JSON objects which have the following keys:

Field Name Type Description
id integer Automatically assigned
name string The Payment Term Name. 64 characters max.

JSON Example

{
  "id": 4,
  "name": "In two installments"
}

Available Methods

HTTP Verb Action
GET Retrieve a resource, you have to specify an id
GET Retrieve the list of resources

Taxes

Endpoint: https://api.oneup.com/v1/taxes

This API is read only.

JSON Format

Taxes are represented as JSON objects which have the following keys:

Field Name Type Description
id integer Automatically assigned
name string The Tax Name. 128 characters max.
rate double The Tax Rate

JSON Example

{
  "id": 5,
  "name": "10% Federal Tax",
  "rate": 10.00
}

Available Methods

HTTP Verb Action
GET Retrieve a resource, you have to specify an id
GET Retrieve the list of resources

Currencies

Endpoint: https://api.oneup.com/v1/currencies

This API is read only.

JSON Format

Currencies are represented as JSON objects which have the following keys:

Field Name Type Description
id integer Automatically assigned
iso_code string The ISO code of the currency (ISO 4217). 4 characters max.
name string The Currency Name. 64 characters max.
is_main_currency boolean Is this currency the main accounting for this domain

JSON Example

{
  "id": 133,
  "iso_code": "USD",
  "name": "U.S. Dollar",
  "is_main_currency": true
}

Available Methods

HTTP Verb Action
GET Retrieve a resource, you have to specify an id
GET Retrieve the list of resources

Units

Endpoint: https://api.oneup.com/v1/units

This API is read only.

JSON Format

Units are represented as JSON objects which have the following keys:

Field Name Type Description
id integer Automatically assigned
name string The Unit Name. 64 characters max.
type integer Describe the kind of unit
1: Piece
2: Weight
3: Dimension
4: Surface
5: Volume
6: Time

JSON Example

{
  "id": 8,
  "name": "Day",
  "type": 6
}

Available Methods

HTTP Verb Action
GET Retrieve a resource, you have to specify an id
GET Retrieve the list of resources

Address

In OneUp, addresses are used at several places. Accounts, Suppliers, Contacts... So, in the API, addresses are embeded into their own JSON format, and follow the same rules everywhere.

JSON Format

Addresses are represented as JSON objects which have the following keys:

Field Name Type Mandatory Read-only Description
street_line1 string no no First line of the address. 255 characters max.
street_line2 string no no Second line of the address. 255 characters max.
street_line3 string no no Third line of the address. 255 characters max.
postal_code string no no The zip code of the address. 128 characters max.
city string no no The city of the address. 128 characters max.
country string no no The country of the address. 128 characters max.
locality string no no The localisaton of the address (limited to the one from the country selected). 255 characters max.
short_locality string no yes The short code for the Country. 10 characters max.
full_address string no yes The full formated adress as it should appears on documents

JSON Example

{
  "street_line1": "567  Sutter St.",
  "street_line2": "",
  "street_line3": "",
  "postal_code": "94102",
  "city": "San Francisco",
  "country": "United States",
  "locality": "California",
  "short_locality": "CA",
  "full_address": "567  Sutter St. San Francisco CA 94102 United States"
}

Contact

JSON Format

Contacts are represented as JSON objects which have the following keys:

Field Name Type Mandatory Read-only Description
id integer no yes Automatically assigned
first_name string no no The First Name of the contact. 255 characters max.
last_name string yes no The Last Name of the contact. 255 characters max.
full_name string no yes The full name of this contact
cell_phone string no no The Cell phone of this contact. 128 characters max.
work_phone string no no The Work phone of this contact. 128 characters max.
home_phone string no no The Home phone of this contact. 128 characters max.
email string no no The Email address of this contact. 255 characters max.
address Address no no The address of this contact
note string no no A note about this contact

JSON Example

{
  "id": 48,
  "first_name": "François",
  "last_name": "Nadal",
  "full_name": "François Nadal",
  "cell_phone": "(415) 555-1234",
  "work_phone": "(415) 555-5678",
  "home_phone": "(415) 555-0000",
  "email": "francois.nadal@oneup.com",
  "address": {
    "street_line1": "21 Backer street",
    "street_line2": "Building D",
    "street_line3": "Fifth Floor",
    "postal_code": "94109",
    "city": "San Francisco",
    "country": "USA",
    "locality": "California",
    "short_locality": "CA",
    "full_address": "21 Backer street Building D Fifth Floor San Francisco CA 94109 USA"
  },
  "note": "A contact that worth to know.\nLike to surf."
}

Order Line

Order lines are product or service lines that are embeded within sales or purchases documents. They contain infos like price, quantity, description, etc...
While adding, removing or updating an order line, related values (such as total, tax amount...) on the contextual document will be updated accordingly.

JSON Format

Order lines are represented as JSON objects which have the following keys:

Field Name Type Mandatory Read-only Description
id integer no yes Automatically assigned
item_id integer yes yes Id of the ordered Product or Service.
description string no no A description of the ordered Product or Service.
Default: The Product or Service default description
quantity double no no The ordered quantity.
Default: 1.00
unit_price_wt double no no Unit Price before Taxes
Default: The Product or Service default sales price
discount_rate double no no Discount rate for this line.
Default: 0.00
tax_id integer no no Not available for US.
Id of the Tax to apply.
is_taxable boolean no no US only.
Shall the tax be applied ?
total double no yes Total before taxes and discount.

JSON Example

{
  "id": 56,
  "item_id": 130,
  "description": "Red Wine - high quality",
  "quantity": 12.0,
  "unit_price_wt": 49.99,
  "discount_rate": 5.0,
  "tax_id": 2,
  "is_taxable": false,
  "total": 569.89
}