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

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 42
Payment/Funding Methods 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
Extended Search API
Added TOC, and Search entities: CREDIT,
DEPARTMENT, CLASS, ITEM, LOCATION,
PROJECT, GLACCOUNT, PURCHASE_ORDER
3/15/18
Payment API;
Purchase Order API
Modified paymentMethod: status, glAccount: required
4/12/18
Payment Entity
Payment status examples
4/23/18
Vendor Entity
remittanceEmail and remittanceEnabled examples
Added VOID enum to credits
Added payment_status examples
5/10/18
Formatting
Transition to google doc source
4 Core MineralTree API User Guide
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
Recoverable
Product needs to be able to recover after any system event returns to
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
CREATE
ENTITY
POST
/mtapi/base/ser
vices/[entityTyp
e]/{companyId}
Create new
entity instance
Request model
in JSON format
to create
Created
model,
including the
unique ID of
the created
entity
UPDATE
ENTITY
PUT
/mtapi/base/ser
vices/[entityTyp
e]
Update entity
Json model to
update. Model
will contain the
id of the entity
to be updated
Updated
entity
GET ENTITY
GET
/mtapi/base/ser
vices/[entityTyp
e]/{id}
Retrieve the
entity.
Empty
Entity
DELETE
ENTITY
DELETE
/mtapi/base/ser
vices/[entityTyp
e]/{id}
If supported will
delete of void
the entity.
Specific
behavior
depends on the
entity.
Empty
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 <USERNAME>:<PASSWORD>
..
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: <SESSION>
...
...
...'
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": <amount [0-9]+[0-9]{2}>,
"currency": "<Currency associated with this amount i.e. USD>"
}
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
/mtapi/base/
services/use
r
GET
Returns full
User objects
None
Current user
object
200, OK
503, Service
Error
403,
Forbidden
/mtapi/base/
services/use
r/companies
GET
List all
companies
that user has
association
with
None
List of
companies
that User
has
association
with.
200, OK
503, Service
Error
403,
Forbidden
/mtapi/base/
services/use
r/company
PUT
Update
existing
company
information.
Including
provding
changes to
Block with
company
information
to modify
Resulting
Company
object
200, OK
503, Service
Error
403,
Forbidden
8 Core MineralTree API User Guide
bank
accounts.
User
{
"user": {
"modified": <Last time user was
modified>,
"id": "<User unique id>", "name": "Rob
Posniak", "emails": [
"email, i.e. rob@mineraltree.com"
]
} }
Company
{
"modified": <Last time user was
modified>,
"id": "<Company unique 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
Request
Status
/mtapi/base/servic
es/pm/{companyI
d}
POST
PaymentM
ethod to
create
200, OK
503, Service Error
403, Forbidden
/mtapi/base/servic
es/pm/{pmId}
GET
No request
object
200, OK
503, Service Error
403, Forbidden
/mtapi/base/servic
es/pm/{pmId}
PUT
Request
object
containing
payment
method
object
200, OK
503, Service Error
403, Forbidden
PaymentMethod JSON
{
"paymentMethod": {
"id": "<Only for update>",
"type": "ACH",
"externalId": "external id",
"status": "Active/Locked",
"bankAccount": {
"name": "accountname",
"accountNumber": "accno <optional>",
"accountBalance": {
"availableBalance": {
"amount": <Gl balance>
}
}
}
}
}
{
"paymentMethod": {
"id": "<Only for update>",
"type": "CREDITCARD",
"externalId": "external id",
10 Core MineralTree API User Guide
"status": "Active/Locked",
"card": {
"name": "card account name"
}
}
}
{
"paymentMethod": {
"id": "<Only for update>",
"type": "UNKNOWN",
"externalId": "external id",
"status": "Active/Locked",
"account": {
"name": "account name"
}
}
}
Vendor API
Endpoint
Method
Description
Request
Response
Status
/mtapi/base/servi
ces/vendor/{com
panyId}
POST
Creates new
Vendor object
Request
object,
containing
Vendor
object.
Vendor
object that
was created
with the
vendor id.
200, OK
503,
Service
Error
403,
Forbidden
/mtapi/base/servi
ces/vendor/{vend
orId}
PUT
Update existing
vendor. Vendor
Id is required for
this call.
Request
object
containing
Vendor object
Vendor
object that
was updated
200, OK
503,
Service
Error
403,
Forbidden
/mtapi/base/servi
ces/vendor/{vend
orId}
GET
Get full vendor
record.
No request
object
Full vendor
record
200, OK
503,
Service
Error
11 Core MineralTree API User Guide
403,
Forbidden
/mtapi/base/servi
ces/vendor/{vend
orId}
DELETE
NOT
SUPPORTED
Vendor JSON
{
"vendor": {
"id": "Unique ID of this vendor <only required during update>",
"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 <optional>",
"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
Description
Request
Response
Status
/mtapi/base/
services/pay
ment/{compa
nyId}
POST
Creates new
external
payment
Request
object,
containing
Payment
object.
Payment
created as a
part of this
request
200, OK
503, Service
Error
403,
Forbidden
13 Core MineralTree API User Guide
/mtapi/base/
services/pay
ment
PUT
Updates the
payment
Request
object
containing
Payment
object
Payment
object that
was updated
200, OK
503, Service
Error
403,
Forbidden
/mtapi/base/
services/pay
ment/{payme
ntId}
GET
Get full
Payment
record.
No request
object
Full Payment
record
200, OK
503, Service
Error
403,
Forbidden
Payment JSON
{
"payment": {
"paymentMethod": {
"id": "<Payment method id>"
},
"fundMethod": {
"type": "CHECK | CREDITCARD | DEBITCARD | VCARD | ACH |
ECHECK | BILLPAY | WIRE | CREDIT | UNKNOWN"
},
"bills": [
{
"id": "<bill id in the system>",
"appliedPaymentAmount": {
"amount": <Bill amount applied to payment ex: 5000
is 50$>
}
}
],
"amount": {
"amount": <Total payment amount ex: 5000 is 50$>
},
"accountingPeriod": {
"id": "<Id of the accounting period>"
},
"transactionDate": "<Payment date>",
"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
/mtapi/base/service
s/bill/{companyId}
POST
Creates new Bill
Request
object,
containing
Bill object.
Bill object that
was created
with the bill id.
200, OK
503,
Service
Error
403,
Forbidde
n
/mtapi/base/service
s/bill/{billId}
PUT
Update existing
Bill. Bill Id is
required for this
call.
Request
object
containing
Bill object
Bill that was
updated
200, OK
503,
Service
Error
403,
Forbidde
n
/mtapi/base/service
s/bill/{billId}
GET
Get full Bill
record.
No request
object
Full Bill record
200, OK
503,
Service
Error
403,
Forbidde
n
/mtapi/base/service
s/bill/{billId}
DELETE
NOT
SUPPORTED
Bill JSON
15 Core MineralTree API User Guide
{
"bill": {
"id": "Unique ID of this bill <only required during update>",
"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": "<due date of this bill ex:2017-03-12>",
"transactionDate": "<Invoice date of this bill ex:2017-03-12>",
"invoiceNumber": "Invoice number for this bill",
"amount": {
"amount": <amount [0-9]+[0-9]{2}>
},
"balance": {
"amount": <amount [0-9]+[0-9]{2}>
},
"totalTaxAmount": {
"amount": <amount [0-9]+[0-9]{2}>
},
"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": <amount (0|[1-9][0-9]?|100)>
},
"taxAmount": {
"amount": <amount [0-9]+[0-9]{2}>
},
"netAmount": {
"amount": <amount [0-9]+[0-9]{2}>
},
"amountDue": {
"amount": <amount [0-9]+[0-9]{2}>
},
"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": <value of quantity>,
"precision": <precision - default 2>
},
"cost": {
"amount": <amount [0-9]+[0-9]>,
"precision": <precision - default 2>
},
"taxRate": {
"amount": <amount (0|[1-9][0-9]?|100)>
},
"taxAmount": {
"amount": <amount [0-9]+[0-9]{2}>
},
"netAmount": {
"amount": <amount [0-9]+[0-9]{2}>
},
"amountDue": {
17 Core MineralTree API User Guide
"amount": <amount [0-9]+[0-9]{2}>
},
"lineNumber": Starts with 0,
"closed": true/false,
"description": "Item description"
}
]
}
}
Credit API
Endpoint
Method
Description
Request
Response
Status
/mtapi/base/
services/cre
dit/{company
Id}
POST
Creates new
Credit
Request
object,
containing
Credit
object.
Credit object
that was
created with
the credit id.
200, OK
503, Service
Error
403,
Forbidden
/mtapi/base/
services/cre
dit/
PUT
Update
existing
Credit.
Credit Id is
required for
this call.
Request
object
containing
Credit object
Credit that
was updated
200, OK
503, Service
Error
403,
Forbidden
/mtapi/base/
services/cre
dit/{creditId}
GET
Get full
Credit
record.
No request
object
Full Credit
record
200, OK
503, Service
Error
403,
Forbidden
/mtapi/base/
services/cre
dit/{creditId}
DELETE
NOT
SUPPORTE
D
/mtapi/base/
services/billc
POST
Creates new
bill credit
Request
object,
containing
Bill credit
object that
was created
200, OK
18 Core MineralTree API User Guide
redit/{compa
nyId}
bill credit
object.
with the bill
credit id.
503, Service
Error
403,
Forbidden
/mtapi/base/
services/billc
redit/
PUT
NOT
SUPPORTE
D
/mtapi/base/
services/billc
redit/{billcred
itId}
GET
Get full bill
credit record.
No request
object
Full Bill
Credit record
200, OK
503, Service
Error
403,
Forbidden
/mtapi/base/
services/billc
redit/void/{bil
lcreditId}
GET
Void bill
credit record
No request
object
Void the bill
credit record
associated
with the bill
and credit
200, OK
503, Service
Error
403,
Forbidden
Credit JSON
{
"credit": {
"creditNumber": "<credit no>",
"transactionDate": "<Credit date>",
"vendor": {
"id": "<Mineraltree id of vendor>"
},
"amount": {
"amount": <Total amount of credit with precision 2 - USD>
},
"externalId": "<External id of credit>",
"status": "Open|Settled|Voided Default:Open",
"memo": "<Memo for the credit>"
}
}
BillCredit JSON
{
"billCredit": {
"transactionDate": "<Credit application date>",
19 Core MineralTree API User Guide
"bill": {
"id": "<Mineraltree id of bill>"
},
"credit": {
"id": "<Mineraltree id of credit>"
},
"amountApplied": {
"amount": <amount applied from credit to billwith precision 2 - USD>
}
}
}
Purchase Order API
Endpoint
Method
Description
Request
Response
Status
/mtapi/base/
services/pur
chaseorder/{
companyId}
POST
Creates new
Purchase
Order
Request
object,
containing
PurchaseOr
der object.
PurchaseOr
der object
that was
created with
the bill id.
200, OK
503, Service
Error
403,
Forbidden
/mtapi/base/
services/pur
chaseorder/{
purchaseOrd
erId}
PUT
Update
existing
PurchaseOr
der.
PurchaseOr
der Id is
required for
this call.
Request
object
containing P
urchaseOrde
r object
PurchaseOr
der that was
updated
200, OK
503, Service
Error
403,
Forbidden
/mtapi/base/
services/pur
chaseorder/{
purchaseOrd
erId}
GET
Get full
purchase
order record.
No request
object
Full Purchas
eOrder
record
200, OK
503, Service
Error
403,
Forbidden
/mtapi/base/
services/pur
chaseorder/{
DELETE
NOT
SUPPORTE
D
20 Core MineralTree API User Guide
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": "<due date of this PO ex:2017-03-12>",
"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": <amount [0-9]+[0-9]{2}>
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": <value of quantity>,
"precision": <precision - default 2>
},
"quantityReceived": {
"value": <value of quantity received>,
"precision": <precision - default 2>
},
"billedQuantity": {
"value": <value of billed quantity>,
"precision": <precision - default 2>
},
"cost": {
"amount": <amount [0-9]+[0-9]>,
"precision": <precision - default 2>
},
"amountDue": {
"amount": <amount [0-9]+[0-9]{2}>
},
"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
/mtapi/base/
services/sub
sidiary/{com
panyId}
POST
Creates new
Subsidiary
Request
object,
containing S
ubsidiary
object.
Subsidiary o
bject that
was created
with the
subsidiary id.
200, OK
503, Service
Error
403,
Forbidden
/mtapi/base/
services/sub
sidiary/{subsi
diaryId}
PUT
Update
existing
Subsidiary.
Subsidiary Id
is required
for this call.
Request
object
containing P
urchaseOrde
r object
Subsidiary th
at was
updated
200, OK
503, Service
Error
403,
Forbidden
/mtapi/base/
services/sub
sidiary/{subsi
diaryId}
GET
Get
full subsidiar
y record.
No request
object
Full Subsidia
ry record
200, OK
503, Service
Error
403,
Forbidden
/mtapi/base/
services/sub
sidiary/{subsi
diaryId}
DELETE
NOT
SUPPORTE
D
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
d}
/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}
POST
Creates new
entitye
Request
object,
containing ent
ity object.
Entity object
that was
created with
the entity id.
200, OK
503, Service
Error
403,
Forbidden
24 Core MineralTree API User Guide
/mtapi/base/se
rvices/account
ingperiod
/mtapi/base/se
rvices/classifi
cation
/mtapi/base/se
rvices/depart
ment
/mtapi/base/se
rvices/glaccou
nt
/mtapi/base/se
rvices/item
/mtapi/base/se
rvices/locatio
n
/mtapi/base/se
rvices/project
/mtapi/base/se
rvices/term
PUT
Update
existing
entity. Entity
Id is required
for this call.
Request
object
containing e
ntity object
Entity that
was updated
200, OK
503, Service
Error
403,
Forbidden
mtapi/base/ser
vices/accounti
ngperiod/{acc
ountingPeriod
Id}
/mtapi/base/se
rvices/classifi
cation/{classif
icationId}
/mtapi/base/se
rvices/depart
ment/{depart
mentId}
/mtapi/base/se
rvices/glaccou
GET
Get full entity
record.
No request
object
Full entity
record
200, OK
503, Service
Error
403,
Forbidden
25 Core MineralTree API User Guide
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": <amount [0-9]+[0-9]>,
"precision": <precision - default 2>
},
"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. <BILL, VENDOR, PAYMENT, CREDIT,
DEPARTMENT, CLASS, ITEM, LOCATION, PROJECT, GLACCOUNT, PURCHASE_ORDER>. 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
Description
id
UUID
modified
Date
30 Core MineralTree API User Guide
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
Total amount on the bill
billOrCredit_totalAmountText
String
billOrCredit_currency
String
billOrCredit_memo
String
Memo inthe bill
billOrCredit_status
Integer
1: Open
2: Settled/Paid
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
Vendor name as it appears on
the check
bill_vendorAddressState
Integer
bill_vendorAchValidationStatus
Integer
bill_vendorSubsidiaryId
String
bill_subsidiaryIds
String
bill_vendorFasterPaymentValidationSta
tus
Bolean
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
Type of this vendor
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
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
external Id for this entity
vendor_primarySubsidiaryId
String
vendor_subsidiaryIds
String
vendor_defaultExpenseAccountId
String
vendor_defaultApAccountId
String
vendor_defaultTermsId
String
vendor_defaultLocationId
String
vendor_defaultDepartmentId
String
vendor_form1099
Boolean
1099 form filing
36 Core MineralTree API User Guide
vendor_defaultDebitAccountId
String
vendor_defaultChannel
Integer
Default payment channel
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
Payment entity
Field
Type
Description
payment_externalId
String
Payment external Id
37 Core MineralTree API User Guide
payment_billCount
Integer
payment_commentCount
Integer
payment_paymentDate
Date
Payment date
payment_scheduledDate
Date
Original scheduled date
payment_sortStatus
Integer
payment_status
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
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
Vendor name for which the
payment is made
payment_vendorName_s
ort
String
payment_vendorNameOn
Check
String
payment_vendorAccount
Number
String
payment_shipDate
Date
payment_amountText
String
40 Core MineralTree API User Guide
payment_checkNum
String
payment_firstApprover
String
payment_paymentPutOn
HoldByApprover
String
payment_modifiedDate
Date
payment_submittedByFir
stName
String
payment_submittedByLa
stName
String
payment_accountName
String
payment_accountNumber
String
payment_accountRouting
Number
String
payment_batchNumber
String
payment_sequenceText
String
payment_documentId
String
payment_documentConte
ntType
String
payment_billCreditTxnDa
te
Date
payment_syncStatus
Integer
payment_subsidiaryId
String
payment_originalSyncErr
orMessage
String
payment_syncErrorExpla
nation
String
41 Core MineralTree API User Guide
payment_isEligibleForRe
sync
Boolean
payment_syncErrorId
String
Dimensions (DEPARTMENT, CLASS, ITEM, LOCATION, PROJECT)
Field
Type
Description
dimension_name
String
dimension_search_name
String
dimension_type
Integer
Identifies if its department,
class etc
dimension_status
Integer
dimension_subsidiaryIds
String
dimension_defaultAmortizationTemplateId
String
dimension_companyItemType
Integer
dimension_externalId
String
Gl Account
Field
Type
Description
gl_account_number_externalId
String
External id from outside source for the
gl account
gl_account_number
String
gl_account_name
String
Name of the gl account
gl_account_suggestion
String
gl_account_type
Integer
Type of gl accounts
42 Core MineralTree API User Guide
gl_account_status
Integer
Status of the gl account
gl_account_subsidiaryIds
String
gl_account_name_sort
String
gl_account_number_sort
String
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
Status of the purchase order
purchaseOrder_isClosed
Boolean
purchaseOrder_billedAmount
Long
purchaseOrder_dueDate
Date
Due date of the purchase order
purchaseOrder_isLinkable
Boolean
purchaseOrder_subsidiaryId
String
Endpoint
Method
Description
Request
Response
Status
/mtapi/base/
services/sea
rch/{compan
yId}/ids
POST
Get a list of
ids to entities
that
correspond
to creteria
Query object
as described
above
Object
containing
an array of
UUID(s) to
identify
200, OK
503, Service
Error
43 Core MineralTree API User Guide
provided in
this query
selected
entities
403,
Forbidden
/mtapi/base/
services/sea
rch/{compan
yId}/objects
PUT
Get a list of
full objects
that
correspond
to creteria
provided in
this query
Query object
as described
above
List of
objects
200, OK
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" : "<HOME, OFFICE, MOBILE, OTHER>",
"number" " "Phone number",
"fax" : "<true|false>"
}
], 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

Navigation menu