Introduction

The MagneticHQ API is a RESTful system designed to facilitate easy access to a wide range of data objects from the Magnetic database for purposes of automation, custom software solutions and other applications.

By using simple HTTPS calls, you can fetch and update information about tasks and clients, create new entries in your databases and use the power of MagneticHQ in any way you imagine.

Overview

Before getting stuck into the MagneticHQ API, there are some things to keep in mind.

The MagneticHQ API base URL is located at https://app.magnetichq.com/Magnetic/rest. All functional calls are added upon this base URL, and form part of the Core, Client or Task API subdivisions. More on this later.

You'll also need a token for almost anything you do. This unique sequence allows us to verify who you are without requiring passwords or login details, allowing you to authenticate users once.

Your token

Your token is a unique, safe way for our API to know who you are.

It is important to understand the purpose of a token. Comprised of a securely generated UUID, your token is associated to your user account. Most of the API calls require this token; without it, we would need to ask for login details every step of the way!

To use the Magnetic API, you must set the Authorization header of your request to Bearer YOUR-TOKEN-HERE. As of early 2023, all other methods of token authentication will fail. For example, if your token was ZZZZZ-YYYYYY-XXXXX, your headers would look something like:

... HeaderA: HeaderAValue Authorization: Bearer ZZZZZ-YYYYYY-XXXXX HeaderC: HeaderCValue ...

Your token can be found on your Personal Settings page, under the API section. The button below will take you straight to the token viewer.

View My Token


The Core API

The MagneticHQ Core API handles functions vital to any usage: authentication, user information and error reporting.

Whether you're building a system to use the Project Management or CRM side of MagneticHQ, you'll definitely need to know what the Core API has to offer.

All calls in the Core API are based on the base URL https://app.magnetichq.com/Magnetic/rest/coreAPI.

Authentication

To use most of MagneticHQ's functions, you'll need to authenticate!

MagneticHQ has two authentication functions: authenticate and login.

authenticate

The Authenticate method takes in an email and password via a GET request, and returns either a valid User object or an error.

GET https://app.magnetichq.com/Magnetic/rest/coreAPI/authenticate?email=testemail@gmail.com&password=YOURSECRETPASSWORD

Possible responses:

  • User object
  • 403 Error (invalid email/password combination)

login

The Login method takes in a token via a GET request, and checks that the token is valid. If the token is valid, a User object is returned, otherwise an error is returned. This is to allow you to simply store a token on your system for future authentication, only needing login details if the token is refreshed.

GET https://app.magnetichq.com/Magnetic/rest/coreAPI/login

Possible responses:

  • User object
  • 401 Error (invalid token)

The User Object

The User Object refers to an object representing a user on the MagneticHQ system.

There are several reasons to access the User object. First and foremost, they contain important information such as their API token, their company role and permissions and their owned tasks and clients.

There are three ways to obtain a User object: authentication (be it with the /authenticate or /login calls, the single lookup /user call or the list /users call.

For security reasons, the API returns cleaned data on non-authentication calls, so as to prevent possible token theft.

User object:

{ id: Long Integer, version: Long Integer, title: String, firstName: String, lastName: String, fullName: String, email: String [max characters = 2000], contactNumber: String, description: String [max characters = 2000], role: Object { id: Long Integer, version: Long Integer, name: String }, grouping: String, skin: String, createdDate: Epoch Date Integer, lastAccessedDate: Epoch Date Integer, company: Object { id: Long Integer, version: Long Integer, name: String, contactPerson: String, contactNumber: String, emailAddress: String, physicalAddress: String, postalAddress: String, website: String, mailDomain: String, description: String, defaultSkin: String, groupingName: String, totalSmsesSent: Integer, totalEmailsSent: Integer, createdDate: Epoch Date Integer, active: Boolean, receiveEmailNotifications: Boolean, hr: Boolean, groupingCodePrefix: String, accountsPrefix: String, notifyMethod: String, retentionPeriod: Integer, signatureRecognition: String, accounts: Boolean, ical: Boolean, pricingPackage: String }, active: Boolean, accounts: Boolean, addGroupings: Boolean, notifyMethod: String, lineManager: User Object [cleaned], hrManager: Boolean, timezone: String, apiToken: String [UUID], receiveDailyNotifications: Boolean, receiveRealTimeNotifications: Boolean, taskView: String, groupingSignedView: String, groupingUnsignedView: String, type: String, annualLeave: Double, sickLeave: Double, compassionateLeave: Double, firstLastInitial: String, }

users

The users GET request, when executed with a valid API token, will return an array of User Objects of all users in the relevant company. This data is cleaned.

GET https://app.magnetichq.com/Magnetic/rest/coreAPI/users

This can return:

  • [User Object 1, User Object 2, ...]
  • 401 Error (invalid token)

user

The user call is a GET request that requires a token and a user ID (which can be retried from several objects). This returns a cleaned user object if the token is valid and it is found, otherwise it shall return an error.

GET https://app.magnetichq.com/Magnetic/rest/coreAPI/user?id=XXXX

This can return:

  • User Object [cleaned]
  • 400 Error (User not found)
  • 401 Error (invalid token)

File Object

The MagneticHQ API also lets you upload files via POST methods.

This requires a File object to exist in the body of the POST request. This post returns a MagneticHQ file object, including the way to access it.

POST File object:

{ name: String [requires file extension], contentType: String, owner: Object { id: Long Integer [owning User ID] } access: String ["PRIVATE" or "PUBLIC"], folder: Object { id: Long Integer } or Null, grouping: Object { id: Long Integer [assocated Grouping ID] }, data: String [Base64-encoded file], }

Returned File object:

{ id: Long Integer, version: Long Integer, name: String, access: String ["PRIVATE" or "PUBLIC"], code: String, size: Long Integer, grouping: Grouping Object, createdDate: Epoch Date Integer, modifiedDate: Epoch Date Integer, owner: User Object }

file

The POST request to upload a file to the MagneticHQ servers. The File Object must be added to the body of the request.

POST https://app.magnetichq.com/Magnetic/rest/coreAPI/file body: [File]

This can return:

  • Magnetic File Object (see above)
  • 401 Error (invalid token)
  • 400 Error (bad or incomplete data provided)

reportError

It's possible to report errors to the MagneticHQ servers. This allows the developers to keep track of possible issues and bugs which may arise.

This is a GET call which takes a token and a message in the query parameters. An error will be logged on the MagneticHQ servers. Please use detailed error messages.

GET https://app.magnetichq.com/Magnetic/rest/coreAPI/reportError?message=Highly+detailed+error+message+here.

This should always return a 200 OK response.


Client API

MagneticHQ provides massive functionality with an in-depth database of all your clients and contacts. Now, with the Client API, your data has never been more accessible for your own custom requirements.

The Client API utilizes two primary models: Contacts and Companies. Not to be confused with User objects and their nested User Company, Contacts and Companies hold both static information such as phone numbers, names and addresses and ongoing comments, check-ins and followups. This allows you to not only make the data available, but allow for customized commenting and follow-ups on your client database.

The Client API uses the URL designator clientsAPI, making the URL base to all calls https://app.magnetichq.com/Magnetic/rest/clientsAPI

Contact Object

The Contact object represents an actual person you communicate with: one of your clients, suppliers or customers.

Depending on your goals, this object will be sent to and received from our API. Keep in mind that we currently do not support sparse objects: please POST full objects, even when data has not been edited in some fields.

Contact object:

{ id: Long Integer, version: Long Integer, title: String, firstName: String, lastName: String, fullName: String, landNumber: String, cellNumber: String, faxNumber: String, email: String, physicalAddress: String, postalAddress: String, position: String, otherInfo: String [max characters = 500], externalReference: String, tag: String [max characters = 500], createdDate: Epoch Date Integer, contactCompany: Contact Company Object, company: User Company Object }

contacts

The contacts GET call takes in a token, a search field ('searchField') and a search value ('searchValue'), and returns all matching results in the form of an array of objects.

GET https://app.magnetichq.com/Magnetic/rest/clientsAPI/contacts?searchField=firstName&searchValue=Simon

OR

GET https://app.magnetichq.com/Magnetic/rest/clientsAPI/contactsWithCustomFieldNames?searchField=firstName&searchValue=Simon

This can return:

  • 200 OK ([Contact Object 1, Contact Object 2, ...])
  • 401 Error (invalid token)

contact

The contact call is a CRUD-suitable function, allowing you to create or edit objects, delete them or access them. This all depends on which kind of request you make. It requires a token and either an ID (for deletion and accession) or a Contact object in the body (to create and edit).

GET https://app.magnetichq.com/Magnetic/rest/clientsAPI/contact?id=XXXX

OR

GET https://app.magnetichq.com/Magnetic/rest/clientsAPI/contactWithCustomFieldNames?id=XXXX

This can return:

  • 200 OK (Contact Object)
  • 400 Error (Contact not found)
  • 401 Error (invalid token)

DELETE https://app.magnetichq.com/Magnetic/rest/clientsAPI/contact?id=XXXX

This can return:

  • 200 OK (delete successful)
  • 400 Error (Contact not found)
  • 401 Error (invalid token)

POST https://app.magnetichq.com/Magnetic/rest/clientsAPI/contact Body: Contact Object [no ID will trigger Contact creation]

OR

POST https://app.magnetichq.com/Magnetic/rest/clientsAPI/contactWithCustomFieldNames Body: Contact Object [no ID will trigger Contact creation]

This can return:

  • 200 OK (Contact Object)
  • 400 Error (Contact not found or bad/incomplete data)
  • 401 Error (invalid token)

contactTags

This GET request returns all the Contact-associated tags for the token owner's company.

GET https://app.magnetichq.com/Magnetic/rest/clientsAPI/contactTags

This can return:

  • 200 OK ([String, String, ...])
  • 401 Error (invalid token)

Company Object

The Contact Company object represents an organization in your database. This company has associated details, and is associated with Contacts who work there.

Being CRUD-compliant, this object is also sent and received to and from the MagneticHQ API.

Company object:

{ id: Long Integer, version: Long Integer, name: String, contactPerson: String, contactNumber: String, emailAddress: String, physicalAddress: String, postalAddress: String, website: String, mailDomain: String, description: String [max characters = 2000], createdDate: Epoch Date Integer, otherInfo: String [max characters = 1500], externalReference: String, tag: String [max characters = 500], taxNumber: String, owner: User Object [cleaned], global: Boolean, company: User Company Object }

companies

The companies GET call takes in a token, a search field ('searchField') and a search value ('searchValue'), and returns all matching results in the form of an array of objects.

GET https://app.magnetichq.com/Magnetic/rest/clientsAPI/companies?searchField=firstName&searchValue=Simon

OR

GET https://app.magnetichq.com/Magnetic/rest/clientsAPI/companiesWithCustomFieldNames?searchField=firstName&searchValue=Simon

This can return:

  • 200 OK ([Contact Company Object 1, Contact Company Object 2, ...])
  • 401 Error (invalid token)

company

The company call is a CRUD-suitable function, allowing you to create or edit objects, delete them or access them. This all depends on which kind of request you make. It requires a token and either an ID (for deletion and accession) or a Contact Company object in the body (to create and edit).

GET https://app.magnetichq.com/Magnetic/rest/clientsAPI/company?id=XXXX

OR

GET https://app.magnetichq.com/Magnetic/rest/clientsAPI/companyWithCustomFieldNames?id=XXXX

This can return:

  • 200 OK (Contact Company Object)
  • 400 Error (Contact not found)
  • 401 Error (invalid token)

DELETE https://app.magnetichq.com/Magnetic/rest/clientsAPI/company?id=XXXX

This can return:

  • 200 OK (delete successful)
  • 400 Error (Contact not found)
  • 401 Error (invalid token)

POST https://app.magnetichq.com/Magnetic/rest/clientsAPI/company Body: Contact Company Object [no ID will trigger Contact Company creation]

OR

POST https://app.magnetichq.com/Magnetic/rest/clientsAPI/companyWithCustomFieldNames Body: Contact Company Object [no ID will trigger Contact Company creation]

This can return:

  • 200 OK (Contact Company Object)
  • 400 Error (Contact not found or bad/incomplete data)
  • 401 Error (invalid token)

contactTags

This GET request returns all the Contact-Company-associated tags for the token owner's company.

GET https://app.magnetichq.com/Magnetic/rest/clientsAPI/companyTags

This can return:

  • 200 OK ([String, String, ...])
  • 401 Error (invalid token)

Comments and Follow-Ups

The Comments & Follow-Ups calls allow you to interact with your workforce around your clients, adding comments, setting follow-ups and keeping record of calls (successful and unsuccessful) and physical check-ins.

The power of this API system lies in the ability to generate or allow comments on all your client objects. This could range from automatically generated messages created by your system, to follow-up reminders and personal comments left by your users. The ability to designate a user as the assigned follow-up owner also taps into Magnetic's notification system, easily and effortlessly.

Comment Object

The Comment Object represents a discrete unit of communication from one of your users, on a client object. This can be received from, or sent to, the Magnetic server.

Note that, due to the complex notification logic, Comments are not CRUD-compliant.

Comment object:

{ id: Long Integer, version: Long Integer, message: String [max characters = 2000], createdDate: Epoch Date Integer, eventDate: Epoch Date Integer, followUpDate: Epoch Date Integer, actualFollowedUpDate: Epoch Date Integer, notifyContact: Boolean [set to True to notify the assigned user of this comment], type: String ["CALL", "COMMENT", "ATTEMPTEDCALL", "CHECKIN" or "BULKEMAIL"], owner: User Object [can be sparse], author: User Object [can be sparse], }

followupCompanyComment

This GET call returns a Comment of the desired ID ('commentId') from a company of the desired ID ('companyId').

GET https://app.magnetichq.com/Magnetic/rest/clientsAPI/followupCompanyComment?commentId=YYYY&companyId=XXXX

This can return:

  • 200 OK (Comment Object)
  • 400 Error (comment or company ID not found)
  • 401 Error (invalid token)

companyComment

This POST request lets you send a Comment object to Magnetic's servers and attach it to a Contact Company object of your choice. It takes in the token and company ID ('id') as query parameters and the Comment Object in the body of the request.

Alternatively, this can also be called via a DELETE request, deleting the comment ('id') from the company ('companyId') in question.

POST https://app.magnetichq.com/Magnetic/rest/clientsAPI/companyComment?companyId=XXXX Body: Comment Object

This can return:

  • 200 OK (Comment Object)
  • 400 Error (no company found, or bad Comment data)
  • 401 Error (invalid token)

DELETE https://app.magnetichq.com/Magnetic/rest/clientsAPI/companyComment?id=YYYY&companyId=XXXX

This can return:

  • 200 OK (delete successful)
  • 400 Error (no company or comment found with that ID)
  • 401 Error (invalid token)

followupContactComment

This GET call returns a Comment of the desired ID ('commentId') from a contact of the desired ID ('contactId').

GET https://app.magnetichq.com/Magnetic/rest/clientsAPI/followupContactComment?commentId=YYYY&contactId=XXXX

This can return:

  • 200 OK (Comment Object)
  • 400 Error (comment or contact ID not found)
  • 401 Error (invalid token)

contactComment

This POST request lets you send a Comment object to Magnetic's servers and attach it to a Contact object of your choice. It takes in the token and contact ID ('id') as query parameters and the Comment Object in the body of the request.

Alternatively, this can also be called via a DELETE request, deleting the comment ('id') from the contact ('contactId') in question.

POST https://app.magnetichq.com/Magnetic/rest/clientsAPI/contactComment?contactId=XXXX Body: Comment Object

This can return:

  • 200 OK (Comment Object)
  • 400 Error (no contact found, or bad Comment data)
  • 401 Error (invalid token)

DELETE https://app.magnetichq.com/Magnetic/rest/clientsAPI/contactComment?id=YYYY&contactId=XXXX

This can return:

  • 200 OK (delete successful)
  • 400 Error (no contact or comment found with that ID)
  • 401 Error (invalid token)

currentFollowups

The currentFollowups GET request takes in a token and returns all upcoming follow-ups assigned to that user in an array format.

This uses a modified form of the Comment object to allow direct linking to Contact and Contact Company IDs.

SparseComment Object:

{ contactName: String or Null [Null if Comment is on the Contact Company], contactId: Long Integer, contactCompanyName: String, contactCompanyId: Long Integer, createdDate: Epoch Date Integer, message: String, authorName: String, followupDate: Epoch Date Integer, followup: Boolean, recordId: Long Integer, type: String ["CALL", "COMMENT", "ATTEMPTEDCALL", "CHECKIN" or "BULKEMAIL"], }

GET https://app.magnetichq.com/Magnetic/rest/clientsAPI/currentFollowups

This can return:

  • 200 OK ([Comment 1, Comment 2, ...])
  • 401 Error (invalid token)


Task API

The third API module is called the Task API, and is aimed at giving you control over your Tasks, Opportunities and Groupings.

This also lets you add comments on Tasks and Opportunities and Groupings.

The Task API uses the URL extension 'tasksAPI', so the full base URL for this module is https://app.magnetichq.com/Magnetic/rest/tasksAPI.

Note: Opportunities and Groupings actually use the same object, referred to as a Grouping object. Opportunities are unsigned objects (signed = False) while Groupings are signed. Keep this in mind when using the API to get a specific type of Grouping.

Task Object

The Task Object represents a small, discrete unit of work, which can be a part of a bigger Grouping or simply by itself. It contains information about the task such as a description, the author and assigned user, expected date and estimated effort.

The Task Object is CRUD-compliant.

Task object:

{ id: Long Integer, version: Long Integer, code: String, task: String [max characters = 1000], description: String, grouping: Grouping Object or Null, createdDate: Epoch Date Integer, completedDate: Epoch Date Integer, startDate: Epoch Date Integer, endDate: Epoch Date Integer, trackingDate: Epoch Date Integer, effortMinutes: Integer, timeMinutes: Integer, complete: Boolean, archive: Boolean, tracking: Boolean, ordering: Integer, groupingOrdering: Integer, tag: String, author: User Object [can be sparse], user: User Object [can be sparse], }

tasks

The tasks call allows you to get a list of tasks by providing a token, and an optional search field ('searchField') and search value ('searchValue').

GET https://app.magnetichq.com/Magnetic/rest/tasksAPI/tasks?searchField=name&searchValue=Report

This can return:

  • 200 OK ([Task Object 1, Task Object 2, ...])
  • 401 Error (invalid token)

task

The task call operates as the CRUD method for Task Objects, allowing creation, deletion, editing and access.

GET https://app.magnetichq.com/Magnetic/rest/tasksAPI/task?id=XXXX

This can return:

  • 200 OK (Task Object)
  • 400 Error (Task ID not found)
  • 401 Error (invalid token)

POST https://app.magnetichq.com/Magnetic/rest/tasksAPI/task Body: Task Object [no ID field will trigger object creation]

This can return:

  • 200 OK (Task Object)
  • 400 Error (invalid data or Task ID not found)
  • 401 Error (invalid token)

DELETE POST https://app.magnetichq.com/Magnetic/rest/tasksAPI/task?id=XXXX

This can return:

  • 200 OK (delete successful)
  • 400 Error (Task ID not found)
  • 401 Error (invalid token)

trackTask

For simplicity, it is possible to track and untrack tasks directly without having to perform a POST command with an updated Task Object. This request takes in a token, a Task Object ID ('id') and a boolean varialbe ('track') indicating whether or not to track the task. This call returns the updated Task Object.

Note that tracking a Task will instantly un-track any other Task.

GET https://app.magnetichq.com/Magnetic/rest/tasksAPI/trackTask?id=XXXX&track=true

This can return:

  • 200 OK (Task Object)
  • 400 Error (Task ID not found or Task not owned by User)
  • 401 Error (invalid token)

currentTasks

Similar to the currentFollowups call, currentTasks takes in a token via a GET request and returns an array of tasks. This array is made up of overdue tasks, upcoming tasks and the currently tracked task.

GET https://app.magnetichq.com/Magnetic/rest/tasksAPI/currentTasks

This can return:

  • 200 OK ([Task Object 1, Task Object 2, ...])
  • 401 Error (invalid token)

taskTags

This GET call returns an array of tags associated with any Tasks owned by that users company. It requires a token.

GET https://app.magnetichq.com/Magnetic/rest/tasksAPI/taskTags

This can return:

  • 200 OK ([String, String, ...])
  • 401 Error (invalid token)

Grouping Object

The Grouping object represents either an Opportunity or Signed Grouping. These are used as a means to combine tasks under one item. For example, a software firm might make a Grouping for each Sprint, while an events company would make one for each event. Potential deals can be created as Unsigned Groupings.

The key factor in these objects that distinguishes Opportunities and Signed Groupings is the signed attribute. If it is true, the object is a Signed Grouping; otherwise it is an Opportunity.

Grouping object:

{ id: Long Integer, version: Long Integer, signed: Boolean, code: String, name: String, extra: String, access: String ["PRIVATE" or "PUBLIC"], createdDate: Epoch Date Integer, modifiedDate: Epoch Date Integer, signedDate: Epoch Date Integer, startDate: Epoch Date Integer, endDate: Epoch Date Integer, archivedDate: Epoch Date Integer, externalReference: String, status: String, amount: Decimal Number, monthlyAmount: Decimal Number, percentageComplete: Integer, complete: Boolean, archive: Boolean, tag: String [max characters = 500], contactCompany: Contact Company Object or Null, contact: Contact Object or Null, owner: User Object, author: User Object, winner: User Object, customFields: [Custom Field Object 1, Custom Field Object 2, ...] }

groupings

The groupings call is similar to other search calls, with one important difference. It takes in two extra fields: a boolean signed value ('signed') and an another boolean archive value ('archive'). Depending on whether you want your search to return Opportunities or Signed Groupings, set the 'signed' field to true or false. If you wish to also return archived Grouping Objects, set 'archive' to true.

GET https://app.magnetichq.com/Magnetic/rest/tasksAPI/taskTags?signed=true&searchField=name&searchValue=Sprint

This can return:

  • 200 OK ([Grouping Object 1 (signed), Grouping Object 2 (signed), ...])
  • 401 Error (invalid token)

GET https://app.magnetichq.com/Magnetic/rest/tasksAPI/taskTags?archive=true&signed=false&searchField=name&searchValue=Sprint

This can return:

  • 200 OK ([Grouping Object 1 (unsigned), Grouping Object 2 (unsigned, archived), ...])
  • 401 Error (invalid token)

grouping

This is the CRUD-compliant grouping call for editing, adding, deleting and accessing Grouping objects.

GET https://app.magnetichq.com/Magnetic/rest/tasksAPI/grouping?id=XXXX

OR

GET https://app.magnetichq.com/Magnetic/rest/tasksAPI/groupingWithCustomFieldNames?id=XXXX

This can return:

  • 200 OK (Grouping Object)
  • 400 Error (Grouping ID not found)
  • 401 Error (invalid token)

POST https://app.magnetichq.com/Magnetic/rest/tasksAPI/grouping Body: Grouping Object [no ID field will trigger object creation]

This can return:

  • 200 OK (Grouping Object)
  • 400 Error (invalid data or Grouping ID not found)
  • 401 Error (invalid token)

DELETE POST https://app.magnetichq.com/Magnetic/rest/tasksAPI/grouping?id=XXXX

OR

POST https://app.magnetichq.com/Magnetic/rest/tasksAPI/groupingWithCustomFieldNames?id=XXXX

This can return:

  • 200 OK (delete successful)
  • 400 Error (Grouping ID not found)
  • 401 Error (invalid token)

groupingTags

This GET call returns an array of tags associated with any Groupings owned by that users company. It requires a token.

GET POST https://app.magnetichq.com/Magnetic/rest/tasksAPI/groupingTags

This can return:

  • 200 OK ([String, String, ...])
  • 401 Error (invalid token)

groupingStatuses

Similar to groupingTags, groupingStatuses allows a user to provide a token and GET a list of statuses associated with Signed Groupings.

GET POST https://app.magnetichq.com/Magnetic/rest/tasksAPI/groupingStatuses

This can return:

  • 200 OK ([String, String, ...])
  • 401 Error (invalid token)

opportunityStatuses

As with groupingStatuses, opportunityStatuses allows a user to provide a token and GET a list of statuses associated with Unsigned Groupings, also known as Opportunities.

GET POST https://app.magnetichq.com/Magnetic/rest/tasksAPI/opportunityStatuses

This can return:

  • 200 OK ([String, String, ...])
  • 401 Error (invalid token)

Custom Fields

MagneticHQ allows you to add a list of special custom fields to your projects, allowing you to add your own values in the form of dates, numbers, lists and choices. These custom fields are accessed through the grouping object, and through the /customFieldDefinitions call.

There are two types of objects: a Custom Field Definition, and a Custom Field.

Custom Field Definition Object

Custom Field Definitions are defined by company administrators and define the 'rules' of the field.

Custom Field Definition Object:

{ id: Long Integer, version: Long Integer, fieldLabel: String [max characters = 50], tooltip: String [max characters = 256], autocompleteSuggestions: String [max characters = 1000], company: Company Object, createdDate: Epoch Date Integer, active: Boolean, required: Boolean, fieldType: String ["NUMBER", "TEXT", "DATE", "DROPDOWN", "CHOICE" or "HEADING"], autocomplete: String ["SUGGEST", "AFTERTYPE" or "NONE"], author: User Object, ordering: Integer }

Custom Field Object

The Custom Field object is the link between a grouping and a definition, containing data relevant to that specific field definition.

Custom Field Object:

{ id: Long Integer, version: Long Integer, textValue: String, dateValue: Epoch Date Integer, numberValue: Decimal Number, customFieldDefinition: Custom Field Definition Object, grouping: Grouping Object [does not recursively contain a Custom Field list], company: Company Object }

groupingCustomFieldDefinitions

This GET call takes your token and returns all Custom Field Definitions set up by your company, in an array.

GET POST https://app.magnetichq.com/Magnetic/rest/tasksAPI/groupingCustomFieldDefinitions

This can return:

  • 200 OK ([Custom Field Definition 1, Custom Field Definition 2, ...])
  • 401 Error (invalid token)

Commenting

Similar to the Client API, the Tasks API allows you to read and leave comments on Tasks, Opportunities and Groupings.

The Task Comment object is not CRUD-compliant. Note that Task Comments can be left on both Tasks and Groupings (Opportunities and Signed Groupings).

Task Comment Object:

{ id: Long Integer, version: Long Integer, text: String, createdDate: Epoch Date Integer, author: User Object [cleaned], task: Task Object, notified: String }

Grouping Comment Object:

{ id: Long Integer, version: Long Integer, text: String, createdDate: Epoch Date Integer, systemMessage: Boolean, author: User Object [cleaned], grouping: Grouping Object, notified: String }

taskComments

To conserve space, Task Comments are not included in the objects accessible from the /tasksAPI/task call. As such, comment lists must be obtained independently by providing this GET call with the ID of the desired Task.

GET https://app.magnetichq.com/Magnetic/rest/tasksAPI/taskComments?id=XXXX

This can return:

  • 200 OK ([Task Comment Object 1, Task Comment Object 2, ...])
  • 400 Error (no Task found)
  • 401 Error (invalid token)

taskComment

The taskComment call can be made via either a POST or DELETE, to create a new Task Comment on the desired Task or to delete a comment from the Task. It takes in either the ID of the Task Comment to delete, or the new Task Comment object in the request body.

POST https://app.magnetichq.com/Magnetic/rest/tasksAPI/taskComment Body: Task Comment Object [can have a sparse task field]

This can return:

  • 200 OK (Task Comment Object)
  • 400 Error (invalid data)
  • 401 Error (invalid token)

DELETE https://app.magnetichq.com/Magnetic/rest/tasksAPI/taskComment?id=XXXX

This can return:

  • 200 OK (delete successful)
  • 400 Error (no Task Comment found)
  • 401 Error (invalid token)

groupingComments

Similar to the taskComments call, groupingComments lets you GET a list of Grouping Comments associated with a particular Opportunity or Grouping.

GET https://app.magnetichq.com/Magnetic/rest/tasksAPI/groupingComments?id=XXXX

This can return:

  • 200 OK ([Grouping Comment Object 1, Grouping Comment Object 2, ...])
  • 400 Error (no Task found)
  • 401 Error (invalid token)

taskComment

The groupingComment call can be made via either a POST or DELETE, to create a new Grouping Comment on the desired Grouping or to delete a comment from the Grouping. It takes in either the ID of the Grouping Comment to delete, or the new Grouping Comment object in the request body.

POST https://app.magnetichq.com/Magnetic/rest/tasksAPI/groupingComment Body: Task Comment Object [can have a sparse task field]

This can return:

  • 200 OK (Grouping Comment Object)
  • 400 Error (invalid data)
  • 401 Error (invalid token)

DELETE https://app.magnetichq.com/Magnetic/rest/tasksAPI/groupingComment?id=XXXX

This can return:

  • 200 OK (delete successful)
  • 400 Error (no Grouping Comment found)
  • 401 Error (invalid token)

Accounts API

The fourth API module is called the Accounts API, and allows companies and users with accounts access to create, access and modify accounts objects such as Item Types and invoice statements.

The Accounts API uses the URL extension 'accountsAPI', so the full base URL for this module is https://app.magnetichq.com/Magnetic/rest/accountsAPI.

Item Type Object

The Item Type Object represents a billable item for your records.

The Item Type Object is CRUD-compliant.

Item Type object:

{ id: Long Integer, version: Long Integer, name: String, externalName: String, salesCode: String, [for Pastel systems] costOfSalesCode: String, [for Pastel systems] zeroRatedSalesCode: String, [for Pastel systems] zeroRatedCostOfSalesCode: String, [for Pastel systems]' cost: Decimal Number, taxType: String ["NO_TAX", "TAX", "ZERO_RATED", "EXEMPT"], archive: Boolean, archivedDate: Epoch Date Integer, createdDate: Epoch Date Integer }

itemTypes

The itemTypes call allows you to get the full list of item types in your company, by providing a token.

GET https://app.magnetichq.com/Magnetic/rest/accountsAPI/itemTypes

This can return:

  • 200 OK ([Item Type Object 1, Item Type Object 2, ...])
  • 401 Error (invalid token)

itemType

The itemType call operates as the CRUD method for Item Type Objects, allowing access, creation, editing and deletion.

GET https://app.magnetichq.com/Magnetic/rest/accountsAPI/itemType?id=XXXX

This can return:

  • 200 OK (Item Type Object)
  • 400 Error (Item Type ID not found)
  • 401 Error (invalid token)

POST https://app.magnetichq.com/Magnetic/rest/accountsAPI/itemType Body: Item Type Object

This can return:

  • 200 OK (new Item Type Object)
  • 400 Error (invalid data or Item Type ID not found)
  • 401 Error (invalid token)

PUT https://app.magnetichq.com/Magnetic/rest/accountsAPI/itemType Body: Item Type Object with ID

This can return:

  • 200 OK (updated Item Type Object)
  • 400 Error (invalid data or Item Type ID not found)
  • 401 Error (invalid token)

DELETE https://app.magnetichq.com/Magnetic/accountsAPI/itemType?id=XXXX

This can return:

  • 200 OK (delete successful)
  • 400 Error (Item Type ID not found, or Item Type is used in existing accounts objects)
  • 401 Error (invalid token)

Line Item Object

A Line Item represents an Item Type associated with an account, as well as any qualifying details such as mark-up and quantity

Line Item Holder object:

{ id: Long Integer, version: Long Integer, itemType: Item Type Object, refCode: String, unit: Decimal Number [the quantity of Item Types used], markup: Decimal Number, ordering: Integer, taxType: String ["NO_TAX", "TAX", "ZERO_RATED", "EXEMPT"], notes: String [max characters = 5000], docType: ["COST_ESTIMATE", "PURCHASE_ORDER", "SUPPLIER_INVOICE", "TAX_INVOICE", "SUPPLIER_CREDIT_NOTE", "CREDIT_NOTE"], parent: Line Item Object }

Accountable Object

The Accountable Object is the template class for all of Magnetic's accounting statement items (Cost Estimates, Purchase Orders, Supplier Invoices, Supplier Credit Notes, Tax Invoices and Credit Notes).

Accountable object:

{ id: Long Integer, version: Long Integer, name: String, description: String [max characters = 5000], refCode: String, tag: String, orderCode: String, paymentTerms: String, tax: Decimal Number [the percentage of added tax], cost: Decimal Number [the cumulative cost of this item], margin: Decimal Number [the projected profit from this item] totalCost: Decimal Number [the final cost of this item], createdDate: Epoch Date Integer, company: Contact Company Object, contact: Contact Object, grouping: Grouping Object, owner: User Object, archive: Boolean }

Account Item Holder Object

The Account Item Holder Object represents an accounting item as well as the line items associated with it.

Account Item Holder object:

{ account: Accountable Object, lineItems: [Line Item Object 1, Line Item Object 2, ...] }

Cost Estimate Object

The Cost Estimate Object represents an estimated cost invoice, usually sent to a customer.

Cost Estimate Object, extends Accountable Object:

{ status: String ["DRAFT", "INTERNALLY_APPROVED", "INTERNALLY_CANCELLED", "ISSUED", "CLIENT_APPROVED", "CLIENT_CANCELLED", "AWAITING_SIGNATURE", "WAITING_TO_BILL", "PART_BILLED", "BILLED"], tag: String, orderCode: String, paymentTerms: String, billed: Decimal Number [the percentage this estimate has been billed], discount: Decimal Number [the percentage discount attached to this estimatate], exportedDate: Epoch Date Integer, realCreatedDate: Epoch Date Integer, deliveryDate: Epoch Date Integer, hideQtyAndCost: Boolean, hideLineTotals: Boolean }

costEstimates

The costEstimates call allows you to get a list of cost estimates in your company, optionally matching a given search field and value.

GET https://app.magnetichq.com/Magnetic/rest/accountsAPI/tasks?archive=[True or False]&searchField=XXX&searchValue=YYY

This can return:

  • 200 OK ([Cost Estimate Object 1, Cost Estimate Object 2, ...])
  • 401 Error (invalid token)

costEstimate

The costEstimate call operates as the CRUD method for Cost Estimate Objects, allowing access, creation, editing and deletion.

GET https://app.magnetichq.com/Magnetic/rest/accountsAPI/costEstimate?id=XXXX

This can return:

  • 200 OK (Account Item Holder Object)
  • 400 Error (Item Type ID not found)
  • 401 Error (invalid token)

POST https://app.magnetichq.com/Magnetic/rest/accountsAPI/costEstimate Body: Account Item Holder Object with a new Cost Estimate

This can return:

  • 200 OK (Account Item Holder Object with a new Cost Estimate)
  • 400 Error (invalid data or Cost Estimate ID not found)
  • 401 Error (invalid token)

PUT https://app.magnetichq.com/Magnetic/rest/accountsAPI/costEstimate Body: Account Item Holder Object with a Cost Estimate

This can return:

  • 200 OK (Account Item Holder Object with updated Cost Estimate Object)
  • 400 Error (invalid data or Cost Estimate ID not found)
  • 401 Error (invalid token)

DELETE https://app.magnetichq.com/Magnetic/accountsAPI/costEstimate?id=XXXX

This can return:

  • 200 OK (delete successful)
  • 400 Error (Cost Estimate ID not found, or Cost Estimate is used in existing accounts objects)
  • 401 Error (invalid token)

Purchase Order Object

The Purchase Order Object represents an expectation of purchase, issued to a client or supplier.

Purchase Order Object, extends Accountable Object:

{ status: String ["DRAFT", "CANCELLED", "CHECKED", "INVOICED", "PART_INVOICED", "ISSUED"], tag: String, quoteCode: String, paymentTerms: String, deliveryAddress: String, billed: Decimal Number [the percentage this order has been billed], proofDate: Epoch Date Integer, deliveryDate: Epoch Date Integer, costEstimate: Cost Estimate Object }

purchaseOrders

The purchaseOrders call allows you to get a list of purchase orders in your company, optionally matching a given search field and value.

GET https://app.magnetichq.com/Magnetic/rest/accountsAPI/purchaseOrders?archive=[True or False]&searchField=XXX&searchValue=YYY

This can return:

  • 200 OK ([Purchase Order Object 1, Purchase Order Object 2, ...])
  • 401 Error (invalid token)

purchaseOrdersFull

The purchaseOrdersFull call allows you to get a list of item types in your company, optionally matching a given search field and value.

GET https://app.magnetichq.com/Magnetic/rest/accountsAPI/purchaseOrdersFull?archive=[True or False]&searchField=XXX&searchValue=YYY

This can return:

  • 200 OK ([Account Item Holder Object 1, Account Item Holder Object 2, ...])
  • 401 Error (invalid token)

purchaseOrder

The purchaseOrder call operates as the CRUD method for Purchase Order Objects, allowing access, creation, editing and deletion.

GET https://app.magnetichq.com/Magnetic/rest/accountsAPI/purchaseOrder?id=XXXX

This can return:

  • 200 OK (Account Item Holder Object)
  • 400 Error (Item Type ID not found)
  • 401 Error (invalid token)

POST https://app.magnetichq.com/Magnetic/rest/accountsAPI/purchaseOrder Body: Account Item Holder Object with a new Purchase Order

This can return:

  • 200 OK (Account Item Holder Object with a new Purchase Order)
  • 400 Error (invalid data or Purchase Order ID not found)
  • 401 Error (invalid token)

PUT https://app.magnetichq.com/Magnetic/rest/accountsAPI/purchaseOrder Body: Account Item Holder Object with a Purchase Order

This can return:

  • 200 OK (Account Item Holder Object with updated Purchase Order Object)
  • 400 Error (invalid data or Purchase Order ID not found)
  • 401 Error (invalid token)

DELETE https://app.magnetichq.com/Magnetic/accountsAPI/purchaseOrder?id=XXXX

This can return:

  • 200 OK (delete successful)
  • 400 Error (Purchase Order ID not found, or Purchase Order is used in existing accounts objects)
  • 401 Error (invalid token)

Supplier Invoice Object

The Supplier Invoice Object represents a bill to this company, from a supplier or service.

Supplier Invoice Object, extends Accountable Object:

{ status: String ["DRAFT", "CANCELLED", "CAPTURED", "CREDITED", "PART_CREDITED", "PAID"], tag: String, quoteCode: String, paymentTerms: String, deliveryAddress: String, billed: Decimal Number [the percentage this order has been billed], paymentDate: Epoch Date Integer, exportedDate: Epoch Date Integer, purchaseOrder: Purchase Order Object }

supplierInvoices

The supplierInvoices call allows you to get a list of Supplier Invoices in your company, optionally matching a given search field and value.

GET https://app.magnetichq.com/Magnetic/rest/accountsAPI/supplierInvoices?archive=[True or False]&searchField=XXX&searchValue=YYY

This can return:

  • 200 OK ([Supplier Invoice Object 1, Supplier Invoice Object 2, ...])
  • 401 Error (invalid token)

supplierInvoicesFull

The supplierInvoicesFull call allows you to get a list of item types in your company, optionally matching a given search field and value.

GET https://app.magnetichq.com/Magnetic/rest/accountsAPI/supplierInvoicesFull?archive=[True or False]&searchField=XXX&searchValue=YYY

This can return:

  • 200 OK ([Account Item Holder Object 1, Account Item Holder Object 2, ...])
  • 401 Error (invalid token)

supplierInvoice

The supplierInvoice call operates as the CRUD method for Supplier Invoice Objects, allowing access, creation, editing and deletion.

GET https://app.magnetichq.com/Magnetic/rest/accountsAPI/supplierInvoice?id=XXXX

This can return:

  • 200 OK (Account Item Holder Object)
  • 400 Error (Item Type ID not found)
  • 401 Error (invalid token)

POST https://app.magnetichq.com/Magnetic/rest/accountsAPI/supplierInvoice Body: Account Item Holder Object with a new Supplier Invoice

This can return:

  • 200 OK (Account Item Holder Object with a new Supplier Invoice)
  • 400 Error (invalid data or Supplier Invoice ID not found)
  • 401 Error (invalid token)

PUT https://app.magnetichq.com/Magnetic/rest/accountsAPI/supplierInvoice Body: Account Item Holder Object with a Supplier Invoice

This can return:

  • 200 OK (Account Item Holder Object with updated Supplier Invoice Object)
  • 400 Error (invalid data or Supplier Invoice ID not found)
  • 401 Error (invalid token)

DELETE https://app.magnetichq.com/Magnetic/accountsAPI/supplierInvoice?id=XXXX

This can return:

  • 200 OK (delete successful)
  • 400 Error (Supplier Invoice ID not found, or Supplier Invoice is used in existing accounts objects)
  • 401 Error (invalid token)

Supplier Credit Note Object

The Supplier Credit Note Object represents a payment to a supplier, in relation to a Supplier Invoice.

Supplier Credit Note Object, extends Accountable Object:

{ status: String ["DRAFT", "CANCELLED", "CAPTURED", "PAID"], tag: String, quoteCode: String, paymentTerms: String, deliveryAddress: String, billed: Integer [the percentage this order has been billed], paymentDate: Epoch Date Integer, exportedDate: Epoch Date Integer, supplierInvoice: Supplier Invoice Object }

supplierCreditNotes

The supplierCreditNotes call allows you to get a list of Supplier Credit Notes in your company, optionally matching a given search field and value.

GET https://app.magnetichq.com/Magnetic/rest/accountsAPI/supplierCreditNotes?archive=[True or False]&searchField=XXX&searchValue=YYY

This can return:

  • 200 OK ([Supplier Credit Note Object 1, Supplier Credit Note Object 2, ...])
  • 401 Error (invalid token)

supplierCreditNotesFull

The supplierCreditNotesFull call allows you to get a list of item types in your company, optionally matching a given search field and value.

GET https://app.magnetichq.com/Magnetic/rest/accountsAPI/supplierCreditNotesFull?archive=[True or False]&searchField=XXX&searchValue=YYY

This can return:

  • 200 OK ([Account Item Holder Object 1, Account Item Holder Object 2, ...])
  • 401 Error (invalid token)

supplierCreditNote

The supplierCreditNote call operates as the CRUD method for Supplier Credit Note Objects, allowing access, creation, editing and deletion.

GET https://app.magnetichq.com/Magnetic/rest/accountsAPI/supplierCreditNote?id=XXXX

This can return:

  • 200 OK (Account Item Holder Object)
  • 400 Error (Item Type ID not found)
  • 401 Error (invalid token)

POST https://app.magnetichq.com/Magnetic/rest/accountsAPI/supplierCreditNote Body: Account Item Holder Object with a new Supplier Credit Note

This can return:

  • 200 OK (Account Item Holder Object with a new Supplier Credit Note)
  • 400 Error (invalid data or Supplier Credit Note ID not found)
  • 401 Error (invalid token)

PUT https://app.magnetichq.com/Magnetic/rest/accountsAPI/supplierCreditNote Body: Account Item Holder Object with a Supplier Credit Note

This can return:

  • 200 OK (Account Item Holder Object with updated Supplier Credit Note Object)
  • 400 Error (invalid data or Supplier Credit Note ID not found)
  • 401 Error (invalid token)

DELETE https://app.magnetichq.com/Magnetic/accountsAPI/supplierCreditNote?id=XXXX

This can return:

  • 200 OK (delete successful)
  • 400 Error (Supplier Credit Note ID not found, or Supplier Credit Note is used in existing accounts objects)
  • 401 Error (invalid token)

Tax Invoice Object

The Tax Invoice Object represents an invoice for services rendered, issued to a client.

Tax Invoice Object, extends Accountable Object:

{ status: String ["DRAFT", "CANCELLED", "ISSUED", "CREDITED", "PART_CREDITED", "PAID","PART_PAID"], tag: String, orderCode: String, paymentTerms: String, deliveryAddress: String, billed: Integer [the percentage this order has been billed], paymentDate: Epoch Date Integer, exportedDate: Epoch Date Integer, hideQtyAndCost: Boolean, hideLineTotals: Boolean, costEstimate: Cost Estimate Object }

taxInvoices

The taxInvoices call allows you to get a list of Tax Invoices in your company, optionally matching a given search field and value.

GET https://app.magnetichq.com/Magnetic/rest/accountsAPI/taxInvoices?archive=[True or False]&searchField=XXX&searchValue=YYY

This can return:

  • 200 OK ([Tax Invoice Object 1, Tax Invoice Object 2, ...])
  • 401 Error (invalid token)

taxInvoicesFull

The taxInvoicesFull call allows you to get a list of item types in your company, optionally matching a given search field and value.

GET https://app.magnetichq.com/Magnetic/rest/accountsAPI/taxInvoicesFull?archive=[True or False]&searchField=XXX&searchValue=YYY

This can return:

  • 200 OK ([Account Item Holder Object 1, Account Item Holder Object 2, ...])
  • 401 Error (invalid token)

taxInvoice

The taxInvoice call operates as the CRUD method for Tax Invoice Objects, allowing access, creation, editing and deletion.

GET https://app.magnetichq.com/Magnetic/rest/accountsAPI/taxInvoice?id=XXXX

This can return:

  • 200 OK (Account Item Holder Object)
  • 400 Error (Item Type ID not found)
  • 401 Error (invalid token)

POST https://app.magnetichq.com/Magnetic/rest/accountsAPI/taxInvoice Body: Account Item Holder Object with a new Tax Invoice

This can return:

  • 200 OK (Account Item Holder Object with a new Tax Invoice)
  • 400 Error (invalid data or Tax Invoice ID not found)
  • 401 Error (invalid token)

PUT https://app.magnetichq.com/Magnetic/rest/accountsAPI/taxInvoice Body: Account Item Holder Object with a Tax Invoice

This can return:

  • 200 OK (Account Item Holder Object with updated Tax Invoice Object)
  • 400 Error (invalid data or Tax Invoice ID not found)
  • 401 Error (invalid token)

DELETE https://app.magnetichq.com/Magnetic/accountsAPI/taxInvoice?id=XXXX

This can return:

  • 200 OK (delete successful)
  • 400 Error (Tax Invoice ID not found, or Tax Invoice is used in existing accounts objects)
  • 401 Error (invalid token)

Credit Note Object

The Credit Note Object represents an invoice of credit, in relation to an issued Tax Invoice.

Credit Note Object, extends Accountable Object:

{ status: String ["DRAFT", "CANCELLED", "ISSUED", "CREDITED", "PART_CREDITED", "PAID"], tag: String, orderCode: String, paymentTerms: String, deliveryAddress: String, billed: Integer [the percentage this order has been billed], paymentDate: Epoch Date Integer, exportedDate: Epoch Date Integer, hideQtyAndCost: Boolean, hideLineTotals: Boolean, costEstimate: Cost Estimate Object }

creditNotes

The creditNotes call allows you to get a list of Credit Notes in your company, optionally matching a given search field and value.

GET https://app.magnetichq.com/Magnetic/rest/accountsAPI/creditNotes?archive=[True or False]&searchField=XXX&searchValue=YYY

This can return:

  • 200 OK ([Credit Note Object 1, Credit Note Object 2, ...])
  • 401 Error (invalid token)

creditNotesFull

The creditNotesFull call allows you to get a list of item types in your company, optionally matching a given search field and value.

GET https://app.magnetichq.com/Magnetic/rest/accountsAPI/creditNotesFull?archive=[True or False]&searchField=XXX&searchValue=YYY

This can return:

  • 200 OK ([Account Item Holder Object 1, Account Item Holder Object 2, ...])
  • 401 Error (invalid token)

creditNote

The creditNote call operates as the CRUD method for Credit Note Objects, allowing access, creation, editing and deletion.

GET https://app.magnetichq.com/Magnetic/rest/accountsAPI/creditNote?id=XXXX

This can return:

  • 200 OK (Account Item Holder Object)
  • 400 Error (Item Type ID not found)
  • 401 Error (invalid token)

POST https://app.magnetichq.com/Magnetic/rest/accountsAPI/creditNote Body: Account Item Holder Object with a new Credit Note

This can return:

  • 200 OK (Account Item Holder Object with a new Credit Note)
  • 400 Error (invalid data or Credit Note ID not found)
  • 401 Error (invalid token)

PUT https://app.magnetichq.com/Magnetic/rest/accountsAPI/creditNote Body: Account Item Holder Object with a Credit Note

This can return:

  • 200 OK (Account Item Holder Object with updated Credit Note Object)
  • 400 Error (invalid data or Credit Note ID not found)
  • 401 Error (invalid token)

DELETE https://app.magnetichq.com/Magnetic/accountsAPI/creditNote?id=XXXX

This can return:

  • 200 OK (delete successful)
  • 400 Error (Credit Note ID not found, or Credit Note is used in existing accounts objects)
  • 401 Error (invalid token)