Obeo API Documentation

Available Request Methods

The API only allows the following request types

  • GET
  • POST
  • PUT
  • DELETE

Available End Points

Contacts

  • contacts/add
  • contacts/update
  • contacts/info
  • contacts/delete

Lists

  • lists/add
  • lists/update
  • lists/info
  • lists/delete
  • lists/add-contact
  • lists/remove-contact

Messages

  • messages/send

Authentication

Authentication requires a header on all requests to include the organization API token. Organization tokens are available in the application dashboard.

All requests are made as an organization and only allow access to data within the requested organization.

Header Example:

X-Token: {org_api_key}

Requests

Every request can accept a JSON body instead of post form fields or get url parameters. To enable JSON parsing send a request header to indicate the body is a JSON object.

Content-Type: application/json;

Any JSON body sent with a different content type will be ignored.

Responses

All responses (success or error) will contain a JSON body and application type. A status property will be returned in the root level of all responses. The status property will be ok for successful requests and error for unsuccessful ones.

If the status type is set to error an error message property will also be included error_property. This will include more information about the error.

Example Successful Response

{
  "status": "ok"
}

Example Error Response

{
  "status": "error",
  "error_message": "Human readable info about an error"
}

Any end point that returns a result will have an object inside a root response property.

Example of a successful order request:

{
  "status": "ok",
  "order": { ... order object }
}



Contacts

Contact Object

Contacts are represented by the contact object with the following properties.

{
    "id": "rp_bD1Kjfa",
    "created": "2018-12-03T22:38:32+00:00",
    "updated": "2018-12-04T00:55:26+00:00",
    "phone_number": "(555) 321-9876",
    "first_name": "Mike",
    "last_name": "Franks",
    "full_name": "Mike Franks",
    "email_address": "mfranks@example.com",
    "unsubscribed": false
}

Add New Contact

POST /contacts/add

The only information required to add a contact to an organization is the phone number. A contact does not have to be added to a list when they are created.

Adding a new contact with the same phone number as an existing contact will update the existing contacts information. Contacts will not be duplicated by phone number when adding to an organization.

Input Properties

{
  "phone_number": "15553219876",
  "first_name": "Mike",
  "last_name":  "Franks",
  "email_address": "mfranks@example.com"
}

Get Contact

GET /contacts/info

Returns information about an existing contact using their contact ID.

A successful request will return a contact object. If the contact is not found the request will result in an error.

Input Properties

Either a phone number or ID is required.

{
  "id": "rp_bD1Kjfa",
  "phone_number": ""
}

Update Contact

PUT /contacts/update

Update an existing contact's information and subscription status. Name and email fields will only be updated if they are populated, otherwise no action is taken.

Contacts can only be unsubscribed, a false unsubscribe value will take no action and a true value will permanently unsubscribe a user from the organization.

Input Properties

The only required field is id. Contacts phone numbers can not be updated once set. To change a phone number re-add as a new contact with the new phone number.

{
  "id": "rp_bD1Kjfa",
  "first_name": "Mike",
  "last_name":  "Franks",
  "email_address": "mfranks@example.com",
  "unsubscribed":  false
}

Delete Contact

DELETE /contacts/delete

Remove a contact from the organization, contacts can be re-added after deletion. This does not unsubscribe a contact from the current organization.

Input Properties

Either a phone number or ID is required. This is a GDPR compliant delete method.

{
  "id": "rp_bD1Kjfa",
  "phone_number": ""
}



Addresses

Address Object

A contact address is represented by the address object with the following properties.

{
  "id": "ra_KivxYUX",
  "created": "2018-12-04T17:55:40+00:00",
  "updated": "2018-12-04T17:55:40+00:00",
  "company": "Obeo",
  "address1": "123 Fake St",
  "address2": "#415",
  "city": "San Francisco",
  "province": "California",
  "country": "United States",
  "zip": "94107",
  "province_code": "CA",
  "country_code": "US",
  "country_name": "United States of America",
  "default": "1",
  "human_street": "123 Fake St #415",
  "human_city": "San Francisco, CA 94107"
}

Add New Address

POST /addresses/add

Add a new address to an existing contact. Contact ID, Address 1, Zip, and Default are required fields.

Input Properties

{
  "contact_id":  "rp_RivzYtX",
  "company": "Obeo",
  "address1": "123 Fake St",
  "address2": "#415",
  "city": "San Francisco",
  "province": "California",
  "country": "United States",
  "zip": "94107",
  "province_code": "CA",
  "country_code": "US",
  "country_name": "United States of America",
  "default": "1"
}

Get Address

GET /addresses/info

Returns information about an existing address using the address ID.

A successful request will return an address object. If the address is not found the request will result in an error.

Input Properties

{
  "id": "ra_KivxYUX"
}

Get All Contact Addresses

GET /addresses/contact

Returns an array of contact address objects. Returns an empty array if the contact has none.

Input Properties

{
  "contact_id": "ra_KivxYUX"
}

Get Default Address

GET /addresses/contact-default

Returns a contacts default address object.

Input Properties

{
  "contact_id": "ra_KivxYUX"
}

Update Address

PUT /addresses/update

Update an existing contacts address object information.

Input Properties

ID is a required field.

{
  "id": "sg_tQZqAKB",
  "company": "Obeo",
  "address1": "123 Fake St",
  "address2": "#415",
  "city": "San Francisco",
  "province": "California",
  "country": "United States",
  "zip": "94107",
  "province_code": "CA",
  "country_code": "US",
  "country_name": "United States of America",
  "default": "1"
}

Delete Address

DELETE /addresses/delete

Delete a contact address object.

Input Properties

ID is a required field.

{
  "id": "sg_tQZqAKB"
}



Products

Product Object

A product is represented by the product object with the following properties.

Product ID and Variant ID are user submitted custom values to reference a product in a local system.

{
  "id": "pd_4Pdbml266IBualA2M8A",
  "product_id": "def7d18802cd6c",
  "variant_id": "3eb5e7972f116e",
  "sku": "T-PN-01",
  "name": "Product Name",
  "description": "A product with a name",
  "vendor": "Product Vendor Inc.",
  "product_type": "cheese",
  "created_at": "2018-12-04T17:55:40+00:00",
  "handle": "product-name",
  "updated_at": "2018-12-04T17:55:40+00:00",
  "published_at": "2018-12-04T17:55:40+00:00",
  "tags": "cheese,cheddar",
  "image_source": "https://www.obeo.io/assets/images/logos/obeo@3x.png",
  "price": "14.99",
  "compare_at_price": "18.99",
  "requires_shipping": "1"
}

Add New Product

POST /products/add

Add a new product object. Product ID, SKU, name, and price are required fields.

Input Properties

{
  "product_id": "def7d18802cd6c",
  "variant_id": "3eb5e7972f116e",
  "sku": "T-PN-01",
  "name": "Product Name",
  "description": "A product with a name",
  "vendor": "Product Vendor Inc.",
  "product_type": "cheese",
  "created_at": "2018-12-04T17:55:40+00:00",
  "handle": "product-name",
  "updated_at": "2018-12-04T17:55:40+00:00",
  "published_at": "2018-12-04T17:55:40+00:00",
  "tags": "cheese,cheddar",
  "image_source": "https://www.obeo.io/assets/images/logos/obeo@3x.png",
  "price": "14.99",
  "compare_at_price": "18.99",
  "requires_shipping": "1"
}

Get Product

GET /products/info

Returns information about an existing product using the product ID.

A successful request will return an product object. If the product is not found the request will result in an error.

Input Properties

{
  "id": "pd_4Pdbml266IBualA2M8A"
}

Find Product

GET /products/find

Returns information about an existing product using the custom product and variant ids.

A successful request will return an product object. If the product is not found the request will result in an error.

Input Properties

{
  "product_id": "def7d18802cd6c",
  "variant_id": "3eb5e7972f116e"
}

Update Product

PUT /products/update

Update an existing product's information.

Input Properties

ID is a required field.

{
  "id": "pd_4Pdbml266IBualA2M8A",
  "sku": "T-PN-01",
  "name": "Product Name",
  "description": "A product with a name",
  "vendor": "Product Vendor Inc.",
  "product_type": "cheese",
  "created_at": "2018-12-04T17:55:40+00:00",
  "handle": "product-name",
  "updated_at": "2018-12-04T17:55:40+00:00",
  "published_at": "2018-12-04T17:55:40+00:00",
  "tags": "cheese,cheddar",
  "image_source": "https://www.obeo.io/assets/images/logos/obeo@3x.png",
  "price": "14.99",
  "compare_at_price": "18.99",
  "requires_shipping": "1"
}

Delete Product

DELETE /products/delete

Delete an product object.

Input Properties

ID is a required field.

{
  "id": "pd_4Pdbml266IBualA2M8A"
}



Lists

List Object

Lists are represented by the list object with the following properties.

{
    "id": "sg_tQZqAKB",
    "created": "2018-12-04T17:43:21+00:00",
    "updated": "2018-12-04T17:43:22+00:00",
    "name": "New List",
    "description": "This is a test list",
    "length": 1
}

Add New List

POST /lists/add

The only required field to add a new list to an organization is the name.

Input Properties

{
    "name": "New List",
    "description": "This is a test list"
}

Get List

GET /lists/info

Returns information about an existing list using the list ID.

A successful request will return a list object. If the list is not found the request will result in an error.

Input Properties

{
  "id": "sg_tQZqAKB"
}

Update List

PUT /lists/update

Update an existing list's name and description. Values will only be overwritten if set.

Input Properties

ID is a required field.

{
  "id": "sg_tQZqAKB",
  "name": "Updated List",
  "description": "This is a test list update"
}

Delete List

DELETE /lists/delete

Delete a list with the option to also remove contacts. If the removeContacts property is true the contacts in the list will also be removed. If false (or not present) they will remain in the All Contacts list and any other list association.

Input Properties

ID is a required field.

{
  "id": "sg_tQZqAKB",
  "remove_contacts": false
}



Messages

Message Object

Messages are represented by the message object with the following properties.

{
    "id": "ms_Jxw2Muz",
    "created": "2018-12-04T17:55:40+00:00",
    "sent": "2018-12-04T17:55:40+00:00",
    "received": true,
    "contact_id": "rp_iLRGiNl",
    "message": "This is a test message",
    "units": "1",
    "direction": "out"
}

Send Message

POST /messages/send

Send a new message to a recipient.

Input Properties

{
    "contact_id": "rp_iLRGiNl",
    "message": "This is a test message"
}



Orders

Order Object

A an order is represented by the order object with the following properties.

Contact, shipping address, and products are objects referenced in the other api's.

Order ID is a custom field used to track the orders system ID in a local system. Order Number is a human friendly order number representation.


{
  "id": "od_iMsO2j18lJ6e8F3w147",
  "created": "2019-04-04T22:28:45+00:00",
  "updated": "2019-04-04T22:28:45+00:00",
  "order_id": "213158",
  "placed_date": "2019-04-04T22:28:45+00:00",
  "last_update_date": "2019-04-04T22:28:45+00:00",
  "cancel_date": "2019-04-04T22:28:45+00:00",
  "fulfillment_date": "2019-04-04T22:28:45+00:00",
  "order_number": "#213158",
  "order_note": "Order node",
  "total_price": "302.00",
  "subtotal_price": "300.00",
  "total_tax": "2.00",
  "currency": "usd",
  "payment_status": "paid",
  "paid": true,
  "total_discounts": "0.00",
  "total_line_items_price": "300.00",
  "cancel_reason": "",
  "total_price_usd": "302.00",
  "fulfillment_status": "paid",
  "contact": {
    "id": "rp_bD1Kjfa",
    "created": "2018-12-03T22:38:32+00:00",
    "updated": "2018-12-04T00:55:26+00:00",
    "phone_number": "(555) 321-9876",
    "first_name": "Mike",
    "last_name": "Franks",
    "full_name": "Mike Franks",
    "email_address": "mfranks@example.com",
    "unsubscribed": false
  },
  "shipping_address": {
    "id": "ra_KivxYUX",
    "created": "2018-12-04T17:55:40+00:00",
    "updated": "2018-12-04T17:55:40+00:00",
    "company": "Obeo",
    "address1": "123 Fake St",
    "address2": "#415",
    "city": "San Francisco",
    "province": "California",
    "country": "United States",
    "zip": "94107",
    "province_code": "CA",
    "country_code": "US",
    "country_name": "United States of America",
    "default": "1",
    "human_street": "123 Fake St #415",
    "human_city": "San Francisco, CA 94107"
  },
  "products": [
    {
      "id": "pd_4Pdbml266IBualA2M8A",
      "sku": "T-PN-01",
      "name": "Product Name",
      "description": "A product with a name",
      "vendor": "Product Vendor Inc.",
      "product_type": "cheese",
      "created_at": "2018-12-04T17:55:40+00:00",
      "handle": "product-name",
      "updated_at": "2018-12-04T17:55:40+00:00",
      "published_at": "2018-12-04T17:55:40+00:00",
      "tags": "cheese,cheddar",
      "image_source": "https://www.obeo.io/assets/images/logos/obeo@3x.png",
      "price": "14.99",
      "compare_at_price": "18.99",
      "requires_shipping": "1"
    }
  ]
}

Add New Order

POST /orders/add

Add a new order. Order ID, SKU, name, and price are required fields.

This will only trigger an order placed event regardless of fulfillment_stats.

Input Properties

{
  "contact_id": "rp_bD1Kjfa",
  "shipping_address_id": "ra_KivxYUX",      
  "order_id": "213158",
  "placed_date": "2019-04-04T22:28:45+00:00",
  "last_update_date": "2019-04-04T22:28:45+00:00",
  "cancel_date": "2019-04-04T22:28:45+00:00",
  "fulfillment_date": "2019-04-04T22:28:45+00:00",
  "order_number": "#213158",
  "order_note": "Order node",
  "total_price": "302.00",
  "subtotal_price": "300.00",
  "total_tax": "2.00",
  "currency": "usd",
  "payment_status": "paid",
  "paid": true,
  "total_discounts": "0.00",
  "total_line_items_price": "300.00",
  "cancel_reason": "",
  "total_price_usd": "302.00",
  "fulfillment_status": "paid",
  "products": [
    {
      "id": "pd_4Pdbml266IBualA2M8A",
      "quantity": 1
    }
  ]
}

Add New Order Product Fulfillment

POST /orders/fulfillment

Add a new order product fulfillment. All fields are required.

An order product fulfillment tracks shipping information that can be used in a message to a contact.

Input Properties

{
  "id": "",
  "order_product_id": "",
  "tracking_number":  "",
  "tracking_link": "",
  "service":  ""
}

Add New Order Product Fulfillment

POST /orders/event

Add a new order fulfillment event. Order id, fulfillment id and status are required fields.

Order fulfillment events move an order product fulfillment through the delivery steps triggering events.

Input Properties

{
  "id": "",
  "fulfillment_id": "",
  "status": "",
  "message": ""
}

Available order fulfillment statuses

  • fulfilled
  • partial
  • restocked
  • in_transit
  • label_printed
  • label_purchased
  • attempted_delivery
  • ready_for_pickup
  • confirmed
  • out_for_delivery
  • delivered
  • failure

Get Order

GET /orders/info

Returns information about an existing order using the order ID.

A successful request will return an order object. If the order is not found the request will result in an error.

Input Properties

{
  "id": "od_iMsO2j18lJ6e8F3w147"
}

Find Order

GET /orders/find

Returns information about an existing order using the custom order id.

A successful request will return an order object. If the order is not found the request will result in an error.

Input Properties

{
  "order_id": "213158"
}

Delete Order

DELETE /orders/delete

Delete an order object.

Input Properties

ID is a required field.

{
  "id": "od_iMsO2j18lJ6e8F3w147"
}