Core Mineral Tree API User Guide 5.28

Core%20MineralTree%20API%20User%20Guide%205.28

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 47

DownloadCore Mineral Tree API User Guide 5.28
Open PDF In BrowserView PDF
API USER GUIDE

1

Core MineralTree API User Guide
Core MineralTree API User Guide

2

Document Tracking

3

About This Document

3

Objective

4

Overview

4

The Guiding Principals for these design are:

4

Authentication

5

API Details

6

Models and Objects.

6

Dates

6

Currency

6

Address

6

User & Company API

7

Payment Methods API

9

Vendor API

11

Payment API

13

Bill API

14

Credit API

18

Purchase Order API

20

Subsidiary API

22

Supporting entities API

23

Search API

28

Query Language

28

Examples

28

Allowed search fields per entity

29

Common fields across all entities

29

BILL entity

29

2 ​Core MineralTree API User Guide

VENDOR entity

33

Payment entity

36

Dimensions (DEPARTMENT, CLASS, ITEM, LOCATION, PROJECT)

39

Gl Account

40

Purchase orders

40

Provided for future Implementation and not supported by API now
Payment/Funding Methods

42
42

Bank Account

43

Virtual Card

43

Wire

44

3 ​Core MineralTree API User Guide

Document Tracking
Date

Section

Description

10/01/17

All sections.

Initial Version

11/06/17

Credit API entries

Add credit API documentation

2/20/2018

Added TOC, and Search entities: CREDIT,
DEPARTMENT, CLASS, ITEM, LOCATION,
Extended Search API PROJECT, GLACCOUNT, PURCHASE_ORDER

3/15/18
4/12/18

Payment API;
Purchase Order API
Payment Entity

Modified paymentMethod: status, glAccount: required
Payment status examples
remittanceEmail and remittanceEnabled examples

4/23/18

Vendor Entity

Added VOID enum to credits
Added payment_status examples

5/10/18

Formatting

4 ​Core MineralTree API User Guide

Transition to google doc source

About This Document
This document puts together information and best practices that are necessary in order
to successful use MineralTree API services. This document is an ongoing effort and will
be changed to match new releases of the API.

Objective
The objective of this document is to sufficiently describe all supported API services and
related business models.

Overview
The design of the API is put together in line with REST api best practices and guidance.

The Guiding Principles for these design are:
Principle

Reason

Security

The API will be secured for access to known identities only.
Identification and secure session management will be used to manage
access to the API endpoints.

Scalability

Product has to allow for unlimited elastic scalability. Once of the most
important principles is statelessness of the interactions.

Fault
Product needs to be able to recover after any system event returns to
Recoverable normal, such as network , drive, database, etc failures.
Redundancy

Product has to allow and include a full DR capability in case of a
serious event.

The API is designed using CRUD+Search API design pattern, where each major entity
under management exposes all major/supported aspects of CRUD to the API Users and
any/all retrieval needs are satisfied by exposing a search/query endpoint that would
allow for general retrieval of entities based on desired criteria.
Each major entity in the system will expose its model definition to the API User so that it
could be operated upon with REST entry points. Under the rest guidelines each entity
will potentially support all or a subset of the following calls.

5 ​Core MineralTree API User Guide

CALL

METHOD

Pattern

Description

Request

Response

POST

/mtapi/base/ser
Create new
vices/[entityTyp
entity instance
e]/{companyId}

Created
model,
Request model
including the
in JSON format
unique ID of
to create
the created
entity

UPDATE
ENTITY

PUT

/mtapi/base/ser
vices/[entityTyp Update entity
e]

Json model to
update. Model
will contain the
id of the entity
to be updated

Updated
entity

GET ENTITY

GET

/mtapi/base/ser
Retrieve the
vices/[entityTyp
entity.
e]/{id}

Empty

Entity

DELETE

If supported will
delete of void
/mtapi/base/ser the entity.
vices/[entityTyp Specific
Empty
e]/{id}
behavior
depends on the
entity.

CREATE
ENTITY

DELETE
ENTITY

Empty

The response codes are returned via HTTP codes, as specified in HTTP RFC and
REST best practices. The list of repose codes will be included.

Authentication
The API is authenticated via HTTP Authorization mechanism and is using a user name
and password of the designated API user. In order to enable specific MineralTree user
to be an API user it needs to be specifically enabled.
Once the user has being enabled an authentication request can be performed via
standard HTTP authentication mechanism.
/mtapi/base/security/login
POST /mtapi/base/security/login HTTP/1.1
...
Authorization:MT :
..
HTTP/1.1 200 OK

6 ​Core MineralTree API User Guide

.....
ETag:23a27dbd55e0bc88b4f66924046086de725bc9ab4866d454438aa5013af8e0586a6245a2c215b75a
ac61f450d7ee3197fa28e5240b027766ddd7c0cf93d6d50b

The ETag header will contain a session artifact that would need to be sent back with
every request.
Following successful logging the session artifact can be used to make subsequent
REST calls.
/mtapi/base/services/bill
POST /mtapi/base/services/bill HTTP/1.1
...
If-Match: 
...
...
...'
HTTP/1.1 200 OK
.....
ETag:23a27dbd55e0bc88b4f66924046086de725bc9ab4866d454438aa5013af8e0586a6245a2c215b75a
ac61f450d7ee3197fa28e5240b027766ddd7c0cf93d6d50b

API Details
Models and Objects.
Dates
All dates in the system are represented in 2 formats.
yyyy-MM-dd HH:mm:ss ​ for the long date/time and ​yyyy-MM-dd ​for short date only
representation.

Currency
The currency objects are homogenious within the system and are used everywhere
monetary amounts exist. The format of the Money object is as follows:
{
"amount": ,
"currency": ""
}

Address
The address representation is normalized within the API model and is as follows:
"address" : {
"address1" : "Address line",
"address2" : "Address line",

7 ​Core MineralTree API User Guide

"address3" : "Address line",
"address4" : "Address line",
"address5" : "Address line",
"postalCode" :"Address line",
"town" :"The town",
"ctrySubDivision" :"Country sub-div/state",
"country" :"ISO Country 3-letter code",
"accountNumber" : "Account number"
"accountType" : "Account Type"
}

The naming of these fields is in accordance to ISO naming of addresses.

User & Company API
We are not going to allow for this version of API for clients to create users and
companies.*

Endpoint

Method

Description

Request

Response

Status
200, OK

/mtapi/base/
services/use GET
r

Returns full
None
User objects

503, Service
Current user Error
object
403,
Forbidden

/mtapi/base/
services/use GET
r/companies

List all
companies
that user has None
association
with

List of
companies
that User
has
association
with.

/mtapi/base/
services/use PUT
r/company

Update
existing
company
information.
Including
provding
changes to

8 ​Core MineralTree API User Guide

Block with
company
information
to modify

200, OK
503, Service
Error
403,
Forbidden
200, OK

Resulting
Company
object

503, Service
Error
403,
Forbidden

bank
accounts.

User

Company

{
"user": {
"modified": ,

{
"modified": ", "name": "Rob
Posniak", "emails": [
"email, i.e. rob@mineraltree.com"
]
}}

modified>,
"id": "", "memo":
null,
"name": "Acme", "dBAName": "Acme",
"address": {
"address1": "470 Atlantic", "address2":
null, "address3": null, "address4": null,
"address5": null, "postalCode": "02210",
"town": "Boston", "ctrySubDivision": "MA",
}}
]}

Payment Methods API
In order for the company to be able to enable payments of different types the payment
method needs to be configured. Currently ACH/Bank Account or Credit Card payment
methods are supported.

9 ​Core MineralTree API User Guide

Endpoint

Method

Description

Request

Response

Status
200, OK

/mtapi/base/servic
es/pm/{companyI POST
d}

Creates new
Payment
method

PaymentM
ethod to
create

/mtapi/base/servic
GET
es/pm/{pmId}

Get full PM
record.

No request
Full PM record
object

/mtapi/base/servic
PUT
es/pm/{pmId}

Update existing
payment
method.
Payment
method Id is
required for this
call.

Request
object
containing
payment
method
object

PaymentMethod JSON
{
"paymentMethod": {
"id": "",
"type": "ACH",
"externalId": "external id",
"status": "Active/Locked",
"bankAccount": {
"name": "accountname",
"accountNumber": "accno ",
"accountBalance": {
"availableBalance": {
"amount": 
}
}
}
}
}
{
"paymentMethod": {
"id": "",
"type": "CREDITCARD",
"externalId": "external id",

10 ​Core MineralTree API User Guide

503, Service Error
403, Forbidden

Payment
method object
that was
updated

200, OK
503, Service Error
403, Forbidden

200, OK
503, Service Error
403, Forbidden

"status": "Active/Locked",
"card": {
"name": "card account name"
}
}
}
{
"paymentMethod": {
"id": "",
"type": "UNKNOWN",
"externalId": "external id",
"status": "Active/Locked",
"account": {
"name": "account name"
}
}
}

Vendor API
Endpoint

Method

Description

Request

Response

Status
200, OK

/mtapi/base/servi
ces/vendor/{com POST
panyId}

Creates new
Vendor object

Request
object,
containing
Vendor
object.

Vendor
object that
was created
with the
vendor id.

503,
Service
Error
403,
Forbidden

200, OK
/mtapi/base/servi
ces/vendor/{vend PUT
orId}

/mtapi/base/servi
ces/vendor/{vend GET
orId}

Update existing
vendor. Vendor
Id is required for
this call.

Request
Vendor
object
object that
containing
was updated
Vendor object

503,
Service
Error
403,
Forbidden
200, OK

Get full vendor
record.

11 ​Core MineralTree API User Guide

No request
object

Full vendor
record

503,
Service
Error

403,
Forbidden
/mtapi/base/servi
ces/vendor/{vend DELETE
orId}

NOT
SUPPORTED

Vendor JSON
{
"vendor": {
"id": "Unique ID of this vendor ",
"form1099Enabled": true/false,
"externalId": "Reference id that can be used to reference back to calling system",
"name": "Name of the vendor",
"active": true/false,
"address": {
"name": "address name",
"address1": "Address line 1",
"address2": "Address line 2",
"address3": "Address line 3",
"address4": "Address line 4",
"address5": "Address line 5",
"postalCode": "Postal or Zipcode",
"town": "City or Town",
"ctrySubDivision": "State/Region",
"country" : "Country"
},
"legalName": "Vendor name on check",
"vendorType": "NONPROFIT, CORPORATION, SOLE_PROPRIETORSHIP,
INDIVIDUAL, DICISION, SUBSIDIARY",
"phones": [
{
"number": "Phone number - only one supported now",
"isFax": false
},
{
"number": "Fax number - only one supported now",
"isFax": true
}
],
"fundingMethods": [
{
"type": "ACH",
"bankAccount": {
"accountNumber": "accno ",
"routingNumber" : "routing number in us | sort code in UK"
}
}
],

12 ​Core MineralTree API User Guide

"emails": [
"Vendor emails. Only 1 is supported right now."
],
"remittanceEmails": [
"abc@xyz.com", "def@xyz.com"
],
"remittanceEnabled": true/false,
"memo": "Vendor memp",
"customerAccount" : "Customer account no - String",
"primarySubsidiary": {
"id": "Id of the subsidiary vendor linked to"
},
"taxId": "Tax ID",
"vatNumber": "Vat Number",
"vendorCompanyDefault": {
"defaultClassId": "Default class id of the vendor",
"defaultCustomerId": "Default customer id of the vendor",
"defaultDepartmentId": "Default department id of the vendor",
"defaultEmployeeId": "Default employee id of the vendor",
"defaultItemId": "Default item id of the vendor",
"defaultLocationId": "Default location id of the vendor",
"defaultProjectId": "Default project id of the vendor",
"defaultTermsId": "Default terms id of the vendor",
"defaultDebitAccountId": "Default debit account id of the vendor",
"defaultAPAccountId": "Default AP account id of the vendor",
"defaultExpenseAccountId": "Default expense account id of the vendor",
"defaultPaymentChannelCode": "Default payment channel code of the
vendor"
}
}
}

Payment API

Endpoint

Method

/mtapi/base/
services/pay
POST
ment/{compa
nyId}

Description

Request

Request
Creates new object,
external
containing
payment
Payment
object.

13 ​Core MineralTree API User Guide

Response

Status

200, OK
Payment
503, Service
created as a
Error
part of this
403,
request
Forbidden

/mtapi/base/
services/pay PUT
ment

/mtapi/base/
services/pay
GET
ment/{payme
ntId}

Updates the
payment

Request
object
containing
Payment
object

200, OK
Payment
503, Service
object that
Error
was updated 403,
Forbidden
200, OK

Get full
Payment
record.

No request
object

503, Service
Full Payment
Error
record
403,
Forbidden

Payment JSON
{
"payment": {
"paymentMethod": {
"id": ""
},
"fundMethod": {
"type": "CHECK | CREDITCARD | DEBITCARD | VCARD | ACH |
ECHECK | BILLPAY | WIRE | CREDIT | UNKNOWN"
},
"bills": [
{
"id": "",
"appliedPaymentAmount": {
"amount": 
}
}
],
"amount": {
"amount": 
},
"accountingPeriod": {
"id": ""
},
"transactionDate": "",
"externalId": "external id of the payment",
"checkNumber": check number if it is a check payment(only integer),
"sequenceText": sequence text of the payment(can be the check number or ach sequence text.
Depends on the payment channel
}

14 ​Core MineralTree API User Guide

}

Bill API
Endpoint

Method

Description

Request

Response

Status
200, OK

/mtapi/base/service
POST
s/bill/{companyId}

Request
object,
Creates new Bill
containing
Bill object.

503,
Service
Bill object that Error
was created
with the bill id. 403,
Forbidde
n

200, OK
/mtapi/base/service
PUT
s/bill/{billId}

Update existing
Bill. Bill Id is
required for this
call.

Request
object
containing
Bill object

Bill that was
updated

503,
Service
Error
403,
Forbidde
n
200, OK

/mtapi/base/service
GET
s/bill/{billId}

Get full Bill
record.

/mtapi/base/service
DELETE
s/bill/{billId}

NOT
SUPPORTED

Bill JSON

15 ​Core MineralTree API User Guide

503,
Service
No request
Full Bill record Error
object
403,
Forbidde
n

{
"bill": {
"id": "Unique ID of this bill ",
"externalId": "External ID that will help reference this bill with external system",
"term": {
"id": "Id of the term object"
},
"classification": {
"id": "Id of the class object"
},
"department": {
"id": "Id of the department object"
},
"location": {
"id": "Id of the location object"
},
"subsidiary": {
"id": "Id of the subsidiary object"
},
"dueDate": "",
"transactionDate": "",
"invoiceNumber": "Invoice number for this bill",
"amount": {
"amount": 
},
"balance": {
"amount": 
},
"totalTaxAmount": {
"amount": 
},
"memo": "string",
"poNumber": "ponumber1",
"state": "Any | Open | Settled | PendingSettled | ClosedByCredit | Voided",
"vendor": {
"id": "Id of the vendor object"
},
"expenses": [
{
"classification": {
"id": "Id of the class object"
},
"department": {
"id": "Id of the department object"
},
"location": {
"id": "Id of the location object"
},
"glAccount": {
"id": "Id of the gl account object"
},
"taxRate": {

16 ​Core MineralTree API User Guide

"amount": 
},
"taxAmount": {
"amount": 
},
"netAmount": {
"amount": 
},
"amountDue": {
"amount": 
},
"lineNumber": starts with 0,
"closed": true/false,
"memo": "Memo for the expense"
}
],
"items": [
{
"companyItem": {
"id": "Id of the company item object"
},
"classification": {
"id": "Id of the class object"
},
"department": {
"id": "Id of the department object"
},
"location": {
"id": "Id of the location object"
},
"glAccount": {
"id": "Id of the gl account object"
},
"name": "Name of the item if applicable",
"quantity": {
"value": ,
"precision": 
},
"cost": {
"amount": ,
"precision": 
},
"taxRate": {
"amount": 
},
"taxAmount": {
"amount": 
},
"netAmount": {
"amount": 
},
"amountDue": {

17 ​Core MineralTree API User Guide

"amount": 
},
"lineNumber": Starts with 0,
"closed": true/false,
"description": "Item description"
}
]
}
}

Credit API
Endpoint

Method

Description

Request

Response

Status
200, OK

/mtapi/base/
services/cre
POST
dit/{company
Id}

Request
object,
Creates new
containing
Credit
Credit
object.

/mtapi/base/
services/cre
dit/

Update
existing
Credit.
Credit Id is
required for
this call.

PUT

Credit object
that was
created with
the credit id.

503, Service
Error
403,
Forbidden

200, OK
Request
503, Service
object
Credit that
Error
containing
was updated
403,
Credit object
Forbidden
200, OK

/mtapi/base/
services/cre
dit/{creditId}

GET

/mtapi/base/
services/cre
dit/{creditId}

DELETE

/mtapi/base/ POST
services/billc

Get full
Credit
record.

No request
object

Full Credit
record

503, Service
Error
403,
Forbidden

NOT
SUPPORTE
D
Creates new Request
object,
bill credit
containing

18 ​Core MineralTree API User Guide

Bill credit
object that
was created

200, OK

redit/{compa
nyId}

bill credit
object.

with the bill
credit id.

503, Service
Error
403,
Forbidden

/mtapi/base/
services/billc PUT
redit/
/mtapi/base/
services/billc
GET
redit/{billcred
itId}

/mtapi/base/
services/billc
GET
redit/void/{bil
lcreditId}

NOT
SUPPORTE
D
200, OK
Get full bill
No request
credit record. object

Void bill
No request
credit record object

503, Service
Full Bill
Error
Credit record
403,
Forbidden
Void the bill
credit record
associated
with the bill
and credit

Credit JSON
{
"credit": {
"creditNumber": "",
"transactionDate": "",
"vendor": {
"id": ""
},
"amount": {
"amount": 
},
"externalId": "",
"status": "Open|Settled|Voided Default:Open",
"memo": ""
}
}

BillCredit JSON
{
"billCredit": {
"transactionDate": "",

19 ​Core MineralTree API User Guide

200, OK
503, Service
Error
403,
Forbidden

"bill": {
"id": ""
},
"credit": {
"id": ""
},
"amountApplied": {
"amount": 
}
}
}

Purchase Order API
Endpoint

Method

Description

Request

Response

Status
200, OK

/mtapi/base/
services/pur
POST
chaseorder/{
companyId}

Request
Creates new object,
Purchase
containing
Order
PurchaseOr
der object.

/mtapi/base/
services/pur
chaseorder/{ PUT
purchaseOrd
erId}

Update
existing
PurchaseOr
der.
PurchaseOr
der Id is
required for
this call.

PurchaseOr
der object
that was
created with
the bill id.

Request
object
PurchaseOr
containing P der that was
urchaseOrde updated
r object

503, Service
Error
403,
Forbidden

200, OK
503, Service
Error
403,
Forbidden

200, OK

/mtapi/base/
services/pur
chaseorder/{ GET
purchaseOrd
erId}

Get full
No request
purchase
object
order record.

/mtapi/base/
services/pur DELETE
chaseorder/{

NOT
SUPPORTE
D

20 ​Core MineralTree API User Guide

Full Purchas 503, Service
eOrder
Error
record
403,
Forbidden

purchaseOrd
erId}

PurchaseOrder JSON
{
"purchaseOrder": {
"externalId": "External ID that will help reference this purchase order with external
system",
"vendor": {
"id": "id of the vendor"
},
"classification": {
"id": "Id of the class object"
},
"department": {
"id": "Id of the department object"
},
"location": {
"id": "Id of the location object"
},
"subsidiary": {
"id": "Id of the subsidiary object"
},
"terms": {
"id": "id of the term created"
},
"dueDate": "",
"poNumber": "po number",
"memo": "memo",
"state": "'Closed', 'FullyBilled', 'PartiallyReceived', 'PendingBillingPartiallyReceived',
'PendingBilling', 'PendingReceipt', 'PendingSupervisorApproval', 'RejectedBySupervisor', 'New',
'Released', 'ChangeOrder', 'Received', 'Cancelled'",
"poType": "'Standard', 'DropShip', 'Blanket', 'DropshipBlanket'",
"expenses": [
{
"classification": {
"id": "Id of the class object"
},
"department": {
"id": "Id of the department object"
},
"location": {
"id": "Id of the location object"
},
"glAccount": {
"id": "Id of the gl account object"
},
"amountDue": {
"amount": 

21 ​Core MineralTree API User Guide

},
"lineNumber": starts with 1,
"closed": true/false,
"memo": "Memo for the expense"
}
],
"items": [
{
"companyItem": {
"id": "Id of the company item object"
},
"classification": {
"id": "Id of the class object"
},
"department": {
"id": "Id of the department object"
},
"location": {
"id": "Id of the location object"
},
"glAccount": {
"id": "Id of the gl account object"
},
"name": "Name of the item required",
"quantity": {
"value": ,
"precision": 
},
"quantityReceived": {
"value": ,
"precision": 
},
"billedQuantity": {
"value": ,
"precision": 
},
"cost": {
"amount": ,
"precision": 
},
"amountDue": {
"amount": 
},
"lineNumber": Starts with 1,
"closed": true/false,
"description": "Item description",
"poItemStatus": "'New', 'Released', 'ChangeOrder', 'Received', 'Closed', 'Cancelled'",
}
]
}
}

22 ​Core MineralTree API User Guide

Subsidiary API
Endpoint

Method

Description

Request

Response

Status
200, OK

/mtapi/base/
services/sub
POST
sidiary/{com
panyId}

Request
object,
Creates new
containing S
Subsidiary
ubsidiary
object.

/mtapi/base/
services/sub
PUT
sidiary/{subsi
diaryId}

Update
existing
Subsidiary.
Subsidiary Id
is required
for this call.

Subsidiary o
bject that
was created
with the
subsidiary id.

Request
object
Subsidiary th
containing P at was
urchaseOrde updated
r object

503, Service
Error
403,
Forbidden

200, OK
503, Service
Error
403,
Forbidden
200, OK

/mtapi/base/
services/sub
GET
sidiary/{subsi
diaryId}

Get
No request
full subsidiar
object
y record.

/mtapi/base/
services/sub
DELETE
sidiary/{subsi
diaryId}

NOT
SUPPORTE
D

503, Service
Full Subsidia
Error
ry record
403,
Forbidden

Subsidiary JSON
{
"subsidiary": {
"id": "id - required only for update",
"externalId": "external id of subsidiary - required (cannot be updated)",
"name": "Name of the subsidiary - required",
"externalParentId": "parent id of the subsidiary in the ERP - required (cannot be
updated)"
}
}

23 ​Core MineralTree API User Guide

Supporting entities API
Endpoint

Method

Description

Request

Response

Status

/mtapi/base/se
rvices/account
ingperiod/{co
mpanyId}
/mtapi/base/se
rvices/classifi
cation/{compa
nyId}
/mtapi/base/se
rvices/depart
ment/{compa
nyId}
/mtapi/base/se
rvices/glaccou
nt/{companyI
POST
d}

200, OK
Creates new
entitye

/mtapi/base/se
rvices/item/{c
ompanyId}
/mtapi/base/se
rvices/locatio
n/{companyId
}
/mtapi/base/se
rvices/project/
{companyId}
/mtapi/base/se
rvices/term/{c
ompanyId}

24 ​Core MineralTree API User Guide

Request
object,
containing ent
ity object.

Entity object
that was
created with
the entity id.

503, Service
Error
403,
Forbidden

/mtapi/base/se
rvices/account
ingperiod
/mtapi/base/se
rvices/classifi
cation
/mtapi/base/se
rvices/depart
ment
/mtapi/base/se
rvices/glaccou
PUT
nt
/mtapi/base/se
rvices/item

Update
existing
entity. Entity
Id is required
for this call.

Request
object
containing e
ntity object

200, OK
503, Service
Entity that
Error
was updated
403,
Forbidden

/mtapi/base/se
rvices/locatio
n
/mtapi/base/se
rvices/project
/mtapi/base/se
rvices/term

mtapi/base/ser
vices/accounti
ngperiod/{acc
ountingPeriod
Id}
/mtapi/base/se
rvices/classifi
cation/{classif GET
icationId}

200, OK
Get full entity No request
record.
object

/mtapi/base/se
rvices/depart
ment/{depart
mentId}
/mtapi/base/se
rvices/glaccou

25 ​Core MineralTree API User Guide

Full entity
record

503, Service
Error
403,
Forbidden

nt/{glAccount
Id}
/mtapi/base/se
rvices/item/{c
ompanyItemI
d}
/mtapi/base/se
rvices/locatio
n/{locationId}
/mtapi/base/se
rvices/project/
{projectId}
/mtapi/base/se
rvices/term/{t
ermId}
DELETE

NOT
SUPPORTE
D

Accounting period JSON
{
"accountingPeriod": {
"id": "MT id of the accounting period. Required only for update",
"locked": true/false,
"parentId": "Parent id of the accounting period in ERP",
"year": true/false,
"subName": "Sub name",
"quarter": true/false,
"name": "Accounting period name",
"externalId": "External id of the accounting period - Cannot be updated",
"closed": true/false,
"started": "YYYY-MM-DD start date - no time component",
"ended": "YYYY-MM-DD End date - no time component",
"active": true/false
}
}

Classification JSON
{
"classification": {
"id": "Id of the classification - only for update",
"subsidiaries": [
{

26 ​Core MineralTree API User Guide

"id": "List of the subsidiaries."
},
{
"id": "....."
}
],
"externalId": "External id of classification - cannot be updated",
"name": "Name of the class",
"active": true/false
}
}

Department JSON
{
"department": {
"id": "Id of the department - only for update",
"subsidiaries": [
{
"id": "List of the subsidiaries."
},
{
"id": "....."
}
],
"externalId": "External id of department - cannot be updated",
"name": "Name of the department",
"active": true/false
}
}

GL account JSON
{
"glAccount": {
"id": "Id of the gl account - only for update",
"subsidiaries": [
{
"id": "List of the subsidiaries."
},
{
"id": "....."
}
],
"departmentRequired": true/false,
"locationRequired": true/false,
"projectRequired": true/false,
"customerRequired": true/false,
"vendorRequired": true/false,
"employeeRequired": true/false,
"itemRequired": true/false,
"classRequired": true/false,
"ledgerType": "AP_ACCOUNT | EXPENSE_ACCOUNT | ACCOUNT",
"accountNumber": "Account number",

27 ​Core MineralTree API User Guide

"externalId": "External id of glaccount - cannot be updated",
"name": "Name of gl account",
"active": true/false
}
}

Company item JSON
{
"item": {
"id": "Id of the company item - only for update",
"subsidiaries": [
{
"id": "List of the subsidiaries."
},
{
"id": "....."
}
],
"type": "NONE | INVENTORY | NON_INVENTORY | SERVICE | OTHER_CHARGE |
ASSEMBLY_BILL_OF_MATERIALS | DISCOUNT | SUBTOTAL | DESCRIPTION |
SHIPPING_COST_ITEM | DOWNLOAD_ITEM | GIFT_CERTIFICATE_ITEM | ITEMGROUP | KIT_ITEM |
MARKUP | PAYMENT_ITEM | SALES_INVENTORY | DISCONTINUED | KIT | MISC_CHARGES |
FLAT_FEE",
"cost": {
"amount": ,
"precision": 
},
"residual": {
"amount": residual amount
},
"name": "Name of the item",
"active": true/false,
"externalId": "External id of the item - cannot be updated"
}
}

Location JSON
{
"location": {
"id": "Id of the location - only for update",
"subsidiaries": [
{
"id": "List of the subsidiaries."
},
{
"id": "....."
}
],
"externalId": "External id of location - cannot be updated",
"name": "Name of the location",
"active": true/false
}

28 ​Core MineralTree API User Guide

}

Project JSON
{
"project": {
"id": "Id of the project - only for update",
"externalId": "External id of the project - cannot be updated",
"name": "Name of the Project",
"active": true/false
}
}

Terms JSON
{
"term": {
"id": "Id of the term - only for update",
"subsidiaries": [
{
"id": "List of the subsidiaries."
},
{
"id": "....."
}
],
"dueDays": Discount due in,
"discountDays": Discount days,
"discountPercent": Percentage of discount,
"externalId": "External id of the term - cannot be updated",
"name": "Name of the term",
"active": true/false
}
}

Search API
In order to provide general functionality for querying various data within Mineraltree
system provides general purpose search API.
The search API send a general entity based query object to the server for query
execution.
{
"view": "Views supported by the search processor. . More wil
be added with the new releases",
"query": "QUERY STRING. SEE BELOW",
"page": 0,
"count": N,
"sortField": "use the field from the below table. Default : modified",
"sortAsc": true/false
}

29 ​Core MineralTree API User Guide

Query language is based on the subset of
the ​https://tools.ietf.org/html/draft-nottingham-atompub-fiql-00#section-3.1​ language
specification. Built specifically for REST paradigm it provides simple but extensible
means to support quieries for the MT API
Query Language
The query language is extensible but out of the box it supports the following logical
operations:
●
●
●
●
●
●
●
●

Equal to : ​==
Not equal to : ​!=
Less than : =​ lt=​ or ​<
Less than or equal to : ​=le=​ or <
Greater than operator : =​ gt=​ or >​
Greater than or equal to : =​ ge=​ or ​>=
In : ​=in=
Not in : ​=out=

Examples
vendor_name​=="NameA";​vendor_postalCode​=gt=02482

vendor_name​=="A*"
vendor_name​=="NameA";​bill_dueDate​>"2017-03-20T04:00:00Z"
id​=in=('d94b4b97-01fa-401c-a927-e85a71580cef','d94b4b97-01fa-401c-a927-e85a
713cff')
bill_amountDue​=ge=2000
Allowed search fields per entity
Common fields across all entities

Field

Type

id

UUID

modified

Date

30 ​Core MineralTree API User Guide

Description

created
companyId

UUID

Company Id

31 ​Core MineralTree API User Guide

BILL entity

Field

Type

Description

bill_externalId

String

billOrCredit_vendorId

String

Unique vendor Id associated
with this bill

billOrCredit_vendorExternalId

String

External id of the vendor

billOrCredit_vendorName

String

Name of the vendor for this bill

billOrCredit_vendorName_sort

String

billOrCredit_vendorCategoryId

String

billOrCredit_totalAmount

Long

billOrCredit_totalAmountText

String

billOrCredit_currency

String

billOrCredit_memo

String

Total amount on the bill

Memo inthe bill
1: Open
2: Settled/Paid

billOrCredit_status

Integer

3. Pending Settlement
4. Draft
6. Closed By Credit
8. Awaiting Approval

billOrCredit_batchNumber

String

billOrCredit_batchNumber_string

String

bill_modifiedDate

Date

bill_vendorType

String

bill_vendorRoutingNumber

String

32 ​Core MineralTree API User Guide

bill_vendorAccountNumber

String

bill_vendorDefaultChannel

Integer

bill_vendorNameOnCheck

String

bill_vendorAddressState

Integer

bill_vendorAchValidationStatus

Integer

bill_vendorSubsidiaryId

String

bill_subsidiaryIds

String

Vendor name as it appears on
the check

bill_vendorFasterPaymentValidationSta
Bolean
tus
bill_invoiceNumber

String

Invoice number

bill_txnDate

Date

Transaction date

bill_dueDate

Date

Due date

bill_balanceDue

Long

Balance due on the bill

bill_balanceDueText

String

bill_terms

String

bill_commentCount

Integer

bill_attachmentCount

Integer

bill_discountDays

Integer

bill_discountPercent

Double

bill_appliedBalance

Long

bill_appliedApprovedBalance

Long

bill_isTemplate

Boolean

33 ​Core MineralTree API User Guide

bill_apAccountIds

String

bill_syncStatus

Integer

bill_dataSource

Integer

bill_subsidiaryId

String

bill_cancelledApprovals

Integer

bill_pendingApprovals

Integer

bill_rejectedApprovals

Integer

bill_approvedApprovals

Integer

bill_notsentApprovals

Integer

bill_approvalStatus

Integer

bill_approvalStatusAll

Integer

bill_po_match_status

Integer

bill_approvalBypassStatus

Integer

bill_appliedCreditTotal

Long

bill_appliedNegativeInvoiceTotal

Long

bill_attachmentNames

String

bill_isQueued

Boolean

bill_locationIds

String

bill_departmentIds

String

bill_classIds

String

bill_projectIds

String

bill_itemIds

String

34 ​Core MineralTree API User Guide

bill_employeeIds

String

bill_customerIds

String

bill_glAccountIds

String

bill_poNumbers

String

bill_poStatusValues

String

bill_poClosedStatusValues

String

bill_originalSyncErrorMessage

String

bill_syncErrorExplanation

String

bill_isEligibleForResync

Boolean

bill_syncErrorId

String

bill_vendorMismatch

Boolean

VENDOR entity

Field

Type

Description

vendor_type

INT

vendor_entity_type

String

vendor_vendorCategoryId

String

vendor_name

String

Vendor name on check

vendor_name_string

String

Vendor name

vendor_name_sort

String

vendor_search_name

String

vendor_address1

String

35 ​Core MineralTree API User Guide

Type of this vendor

vendor_address2

String

vendor_address3

String

vendor_address4

String

vendor_address5

String

vendor_city

String

City

vendor_state

String

State

vendor_country

String

Country (US, etc)

vendor_postalCode

String

Postal code

vendor_email_address

String

Email address

vendor_phone

String

vendor_customerAccount

String

vendor_status

Integer

vendor_comment

String

vendor_externalId

String

vendor_primarySubsidiaryId

String

vendor_subsidiaryIds

String

vendor_defaultExpenseAccountId

String

vendor_defaultApAccountId

String

vendor_defaultTermsId

String

vendor_defaultLocationId

String

vendor_defaultDepartmentId

String

vendor_form1099

Boolean

36 ​Core MineralTree API User Guide

external Id for this entity

1099 form filing

vendor_defaultDebitAccountId

String

vendor_defaultChannel

Integer

vendor_achValidationStatus

Integer

vendor_addressState

Integer

vendor_availableCredit

Long

vendor_billerId

String

vendor_vpaEmail

String

vendor_sharefileEmail

String

vendor_amexTokenEmail

String

vendor_channelAchEnabled

Boolean

vendor_channelCheckEnabled

Boolean

vendor_channelBillPayEnabled

Boolean

vendor_channelCardEnabled

Boolean

vendor_channelWireEnabled

Boolean

vendor_channelFasterPaymentsEnabled

Boolean

vendor_wireSubChannel

Integer

vendor_defaultCardSubchannel

Integer

vendor_availableNegativeInvoice

Long

Default payment channel

Payment entity

Field
payment_externalId

Type
String

37 ​Core MineralTree API User Guide

Description
Payment external Id

payment_billCount

Integer

payment_commentCount Integer
payment_paymentDate

Date

Payment date

payment_scheduledDate

Date

Original scheduled date

payment_sortStatus

Integer
Payment status
Ex: If you need to search
for all paid payments,
search against the following
statuses
Manual Check = 1070
Biller portal = 1120
Manual Card = 1110
Other Payments = 1010

payment_status

Integer

Other statuses(Above are
the important statuses and
what follows are just for
understanding the status
returned as part of payment
API)
// Don't change the
order or values here! as
these represent ranges of
state in the db!
Open = 1;
ForApproval = 10;
Recalled = 13;
Modified = 15;
Hold = 20;
Rejected=30;
FirstLevelApproved=900;
Approved=1000;

38 ​Core MineralTree API User Guide

Closed=1030;
LegacyPaymentClosed=10
40;
CheckIssueACK=1050;
CheckPrinted=1060;
CheckLocalPrint=1070;
ACHReturn=1080;
CheckMailed=1090;
CheckCanceled=1100;
CardCompleted=1110;
BillerDirectCompleted=112
0;
ProcessedRangeEnd
= 1121;
Voided = 2000;
Dissolved = 2050;
LockedByCompany=3000;
BlockedByAccountLimit =
3100;
AccountEdit=4000;
PaymentBillModified=4010;
LegacyPaymentCreated=4
020;
BillPaymentModified=4040;

39 ​Core MineralTree API User Guide

CreditModifiedOnBill=4050;
Created=4060;
ForApprovalByService=407
0;
CreatedByService=4080
Queued=6000;

payment_channel

Integer

Payment channel (Check,
ACH, CreditCard.....)

payment_subChannel

Integer

Payment subchannel
(VISA, AMEX...)

payment_amount

Long

Total amount of the
payment

payment_currency

String

payment_dueDate

Date

payment_vendorId

String

payment_vendorName

String

payment_vendorName_s
ort

String

payment_vendorNameOn
String
Check
payment_vendorAccount
String
Number
payment_shipDate

Date

payment_amountText

String

40 ​Core MineralTree API User Guide

Vendor name for which the
payment is made

payment_checkNum

String

payment_firstApprover

String

payment_paymentPutOn
HoldByApprover

String

payment_modifiedDate

Date

payment_submittedByFir
String
stName
payment_submittedByLa
stName

String

payment_accountName

String

payment_accountNumber String
payment_accountRouting
String
Number
payment_batchNumber

String

payment_sequenceText

String

payment_documentId

String

payment_documentConte
String
ntType
payment_billCreditTxnDa
Date
te
payment_syncStatus

Integer

payment_subsidiaryId

String

payment_originalSyncErr
String
orMessage
payment_syncErrorExpla
String
nation

41 ​Core MineralTree API User Guide

payment_isEligibleForRe
sync

Boolean

payment_syncErrorId

String

Dimensions (DEPARTMENT, CLASS, ITEM, LOCATION, PROJECT)

Field

Type

dimension_name

String

dimension_search_name

String

dimension_type

Integer

dimension_status

Integer

dimension_subsidiaryIds

String

dimension_defaultAmortizationTemplateId

String

dimension_companyItemType

Integer

dimension_externalId

String

Description

Identifies if its department,
class etc

Gl Account

Field

Type

gl_account_number_externalId

String

gl_account_number

String

gl_account_name

String

gl_account_suggestion

String

gl_account_type

Integer

42 ​Core MineralTree API User Guide

Description
External id from outside source for the
gl account

Name of the gl account

Type of gl accounts

gl_account_status

Integer

gl_account_subsidiaryIds

String

gl_account_name_sort

String

gl_account_number_sort

String

Status of the gl account

Purchase orders

Field

Type

Description

purchaseOrder_externalId

String

External id of the purchase
order

purchaseOrder_number

String

Purchase order number

purchaseOrder_vendorId

String
Long

purchaseOrder_status

Integer

purchaseOrder_isClosed

Boolean

purchaseOrder_billedAmount

Long

purchaseOrder_dueDate

Date

purchaseOrder_isLinkable

Boolean

purchaseOrder_subsidiaryId

String

Endpoint

Method

/mtapi/base/
services/sea
POST
rch/{compan
yId}/ids

Description

Status of the purchase order

Due date of the purchase order

Request

Get a list of
ids to entities Query object
as described
that
correspond above
to creteria

43 ​Core MineralTree API User Guide

Response
Object
containing
an array of
UUID(s) to
identify

Status
200, OK
503, Service
Error

provided in
this query

/mtapi/base/
services/sea
PUT
rch/{compan
yId}/objects

Get a list of
full objects
that
correspond
to creteria
provided in
this query

selected
entities

403,
Forbidden

200, OK
Query object
List of
as described
objects
above

503, Service
Error
403,
Forbidden

Provided for future Implementation and not
supported by API now
Payment/Funding Methods
There is a normalized, homogenous structure in the models of the MT API around
Payment and Funding methods.
A payment/funding method is the means (methods) by which transfer value from a
single debtor to a single creditor.
Examples of these methods are
Debtor → ACH → Creditor
Debtor → WIRE → Creditor
Debtor → Virtual Card → Creditor
Debtor → Bill Pay → Creditor
Debtor → Credit/Debt Card → Creditor
......
The difference between funding method and payment method is semantical only. In the
transfer where an intermediary party ahas to move funds

44 ​Core MineralTree API User Guide

or process around funds more then once in order to get from ultimate creditor to
ultimate debtor we can have the following picture:
Debtor → ACH → Payment Processor → WIRE Creditor
Structurally both of these are the same but their semantic meaning is different and both
have to be present in the exchange.
The structure of the PaymentMethod object is the following:
{
"bankAccount|virtualCard|Wire|Check|card": {
The content of the structure depends on the object type. See below*
},
"accountType": "CREDITCARD(1), DEBITCARD(2), VCARD(3), ACH(4), ECHECK(5), CHECK(6),
BILLPAY(7), WIRE(8)",
"id": "Global Unique Identifier. if the object has one.",
"externalId": "External ID for reference",
"name": "Used to name payment method"
}

Bank Account
{
"id" : "Global Unique Identifier. If one is appropriate",
"externalId" : "If reference needs to be retained to external id"
"name" : "Name of the Bank",
""
"address" : {
"address1" : "Address line",
"address2" : "Address line",
"address3" : "Address line",
"address4" : "Address line",
"address5" : "Address line",
"postalCode" :"Address line",
"town" :"The town",
"ctrySubDivision" :"Country sub-div/state",
"country" :"ISO Country 3-letter code",
"accountNumber" : "Account number"
"accountType" : "Account Type"
}
"routingNumber" : "The bank account routing number"
}

45 ​Core MineralTree API User Guide

Virtual Card
{
"id" : "Global Unique Identifier. If one is appropriate",
"externalId" : "If reference needs to be retained to external id"
"token" : {
"blocked" : "true|false",
"bin" : "A bin associated with this card",
"expiration" : "MMYY",
"last4" : "Last 4 of the card",
"first6" : "First 6 of the card",
}
"address" : {
"address1" : "Address line",
"address2" : "Address line",
"address3" : "Address line",
"address4" : "Address line",
"address5" : "Address line",
"postalCode" :"Address line",
"town" :"The town",
"ctrySubDivision" :"Country sub-div/state",
"country" :"ISO Country 3-letter code",
"accountNumber" : "Account number"
"accountType" : "Account Type"
},
"phones" : [
{
"location" : "",
"number" " "Phone number",
"fax" : ""
}
], List of phone numbers
"emails" : [
{
"VALID EMAIL"
}
] - List of valid emails.
"routingNumber" : "The bank account routing number"
}

Wire
{
"id" : "Global Unique Identifier. If one is appropriate",
"externalId" : "If reference needs to be retained to external id"
"name" : "Name of the Bank",
""
"address" : {
"address1" : "Address line",
"address2" : "Address line",

46 ​Core MineralTree API User Guide

"address3" : "Address line",
"address4" : "Address line",
"address5" : "Address line",
"postalCode" :"Address line",
"town" :"The town",
"ctrySubDivision" :"Country sub-div/state",
"country" :"ISO Country 3-letter code",
"accountNumber" : "Account number"
"accountType" : "Account Type"
}
"IBAN" : "International Bank Account Number",
"swiftCode" : "SWIFT code number",
"locale" : "Correct Locale settings i.e. us_en",
"currency" : "USD|CAD|.....",
}

47 ​Core MineralTree API User Guide



Source Exif Data:
File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.5
Linearized                      : Yes
Producer                        : Skia/PDF m68
Page Count                      : 47
EXIF Metadata provided by EXIF.tools

Navigation menu