Import and modify data via mutation API
You can import or modify FA data via GraphQL mutation API. When you import an object (for example, a contact or a portfolio), you need to provide all required fields as parameters. The required fields and attributes are the same as in CSV import files, but they need to be referred to without their code prefixes (see Importing in FA Back reference).
When modifying an object, you need to provide the minimum information needed to identify the entity. The imported attributes are updated and attributes that you leave out preserve their previous values.
To import or modify different object types, use the following endpoints:
Contacts => importContacts
Portfolios => importPortfolios
Securities => importSecurities
Transactions => importTransactions
Trade orders => importTradeOrders
Security prices => importPrices
You can adjust the import behavior by using the importGeneral endpoint and specifying the import parameters you need:
rows: list of objects to import (required)withRules: boolean whether to run rules when importing (default = false)importAsync: boolean whether to use asynchronous importing or not (default = false)mode/sMode/pMode/prMode/trMode/oMode/cMode: option to control import behavior for all object types (mode) or specific object type (sMode / pMode / prMode / trMode / oMode / cMode). Available options are:0 - insert and update (default)
1- insert only
2 - update only
Each endpoint can be used to import or update one or many objects in one request. The response identifies if the request was successful or if it had errors (specified in the response).
Define the request
For a valid request such as the example below which shows how to import, you need to define the mutation endpoint to use and all the required fields and attributes. The required fields in this case are "Contact ID", "Name", "Type", "Juridical form", "Status", "Tax country", "Classification", and "Identity" (see File format for importing contacts in FA Back reference).
mutation {
importContacts(contactList: [
{
contactId:"GQL1",
name:"GraphQL contact",
type:"1",
taxCountry:"FI",
juridical:"PE",
status:"A",
classification:"PROF",
identity:"ID"
}, {
....
},
...
])
}You can find an example of how to use importGeneral to control whether to run rules in Import data and trigger a business rule.
Interpret the response
The response structure is similar to the request. The result contains a list of map structures. Each item in the list represents an imported object. All attributes, including the ones not explicitly used in the request, are returned. The attributes have prefixes. For example, contact name is shown as c.name. The importStatus attribute indicates success with the value "OK".
{
"data": {
"importContacts": [
{
"c.marketingCommunication": "",
"c.subType": "",
"c.language": "",
"c.type": "1",
"c.taxCountry": "FI",
"c.externalId": "",
"c.memo": "",
"c.country": "",
"c.phone2": "",
"c.phone1": "",
"c.juridical": "PE",
"c.representatives": "*** ,",
"c.fax": "",
"c.email": "",
"c.extContactIdList": "",
"c.name": "GraphQL contact",
"c.status": "A",
"c.profileAttributes": "",
"c.classification3": "",
"c.contactExchanges": "",
"importStatus": "OK",
"c.electronicCommunication": "",
"c.classification2": "",
"c.transactionExtIdLevel": "1",
"c.address1": "",
"c.address2": "",
"c.tags": "",
"c.nationality": "",
"c.city": "",
"c.classification": "PROF",
"c.contactId": "GQL1",
"c.identity": "ID",
"c.zipCode": ""
},...
]
}
If required attributes are missing or the code is incorrect, the importStatus attribute value is "ERROR". Each attribute with an error shows "ERROR" (or ERROR:[ImportError.required] if the required value is missing).
{
"data": {
"importContacts": [
{
"c.marketingCommunication": "",
"c.subType": "",
"c.language": "",
"c.type": "1",
"c.externalId": "",
"c.taxCountry": "ERROR:[ImportError.required]",
"c.memo": "",
"c.country": "",
"c.phone2": "",
"c.phone1": "",
"c.juridical": "ERROR:[ImportError.required]",
"c.representatives": "*** ,",
"c.fax": "",
"c.email": "",
"c.extContactIdList": "",
"c.name": "GraphQL contact",
"c.status": "ERROR:[ImportError.required]",
"c.profileAttributes": "",
"c.classification3": "",
"c.contactExchanges": "",
"importStatus": "ERROR",
"c.electronicCommunication": "",
"c.classification2": "",
"c.address1": "",
"c.address2": "",
"c.tags": "",
"c.nationality": "",
"c.city": "",
"c.classification": "ERROR:[ImportError.required]",
"c.contactId": "GQL2",
"c.identity": "ERROR:[ImportError.required]",
"c.zipCode": ""
}
]
}
}