Core Mineral Tree API User Guide 5.28
Core%20MineralTree%20API%20User%20Guide%205.28
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 47
| Download | |
| Open PDF In Browser | View 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 : 47EXIF Metadata provided by EXIF.tools