Articles in this section

ImportController overview

Updated
Follow


•    Base route: /api/Import
•    Authentication: Basic auth. In Postman, set Authorization type to Basic and provide your username/password. In code, this is enforced by BasicAuthentication.


POST /api/Import/ImportWithMapping

POST /api/Import/ImportWithMapping Purpose:
•    Creates an import instance (optional) and imports multiple entity types using provided mappings.
•    Returns counts per section and the created ImportInstanceID.

Headers:
•    Content-Type: application/json
•    Authorization: Basic <base64(user:password)>

Body schema summary:
•    InstanceDesc: optional string label for this import instance.
•    For each section, provide data array and a mapping array. Supported sections:
•    Contacts, Payments, Attributes, Lists, Notes
•    PaymentAttributes, PaymentDistributions
•    RecurringPayments, RecurringPaymentAttributes, RecurringPaymentDistributions
•    Mapping format is defined by ImportService.MappingEntry (typically pairs of source field -> destination field).

Example Postman request body (mandatory columns in bold): 

Scenario A: Contact + Payment + PaymentAttributes linked by ImportLinkID

{
 "InstanceDesc": "Import run - Contact + Payment",
 "Contacts": [
  {
     "LinkKey": 1001,
     "Title": "Ms",
     "First": "Taylor",
     "Middle": "A.",
     "Last": "Morgan",
     "Email": "taylor.morgan@example.com",
     "Mobile": "021234567",
     "JoinDt": "2025-12-10",
     "Active": true,
      "Mail": true
   }
 ],
 "ContactsMapping": [  

    { "Source": "LinkKey", "Target": "ImportLinkID", "Type": "int" },
    { "Source": "Title", "Target": "Title", "Type": "string" },
    { "Source": "First", "Target": "FirstName", "Type": "string" },
    { "Source": "Middle", "Target": "Middlename", "Type": "string" },
    { "Source": "Last", "Target": "LastName", "Type": "string" },
    { "Source": "Email", "Target": "EmailAddress", "Type": "string" },
    { "Source": "Mobile", "Target": "MobilePhone", "Type": "string" },
    { "Source": "JoinDt", "Target": "JoinDate", "Type": "date" },
    { "Source": "Active", "Target": "ActiveFlag", "Type": "bool" },
    { "Source": "Mail", "Target": "OKToContact", "Type": "bool" }
 ],

 "Payments": [
   {
     "LinkKey": 1001,
     "Date": "2026-01-10",
     "Amount": "25.50",
     "Campaign": "Summer Appeal",
     "Category": "Donation",
     "PaymentType": "Card",
     "Reference": "P-2026-00001"
   }
 ],
 "PaymentsMapping": [
   { "Source": "LinkKey", "Target": "ImportLinkID", "Type": "int" },
   { "Source": "Date", "Target": "PaymentDate", "Type": "date" },
   { "Source": "Amount", "Target": "Amount", "Type": "decimal" },
   { "Source": "Campaign", "Target": "Campaign", "Type": "string" },
   { "Source": "Category", "Target": "Category", "Type": "string" },
   { "Source": "PaymentType", "Target": "PaymentType", "Type": "string" },
   { "Source": "Reference", "Target": "Reference", "Type": "string" }
 ],

 "PaymentAttributes": [
   {
     "LinkKey": 1001,
     "AttrGroup": "Donation",
     "AttrType": "Method",
     "Attr": "Online",
     "Value": "Yes",
     "Start": "2026-01-10",
     "PaymentRef": "P-2026-00001"
   }
 ],
 "PaymentAttributesMapping": [
   { "Source": "LinkKey", "Target": "ImportLinkID", "Type": "int" },
   { "Source": "AttrGroup", "Target": "AttributeGroup", "Type": "string" },
   { "Source": "AttrType", "Target": "AttributeType", "Type": "string" },
   { "Source": "Attr", "Target": "Attribute", "Type": "string" },
   { "Source": "Value", "Target": "AttributeValue", "Type": "string" },
   { "Source": "Start", "Target": "Startdate", "Type": "date" },
   { "Source": "PaymentRef", "Target": "PaymentReference", "Type": "string" }
 ]
}

Scenario B: Contact + Attributes + Notes linked by ImportLinkID

{
 "InstanceDesc": "Import run - Contact + Attributes + Notes",
 "Contacts": [
   {
     "LinkKey": 2005,
     "First": "Jordan",
     "Last": "Lee",
     "Email": "jordan.lee@example.org",
     "City": "Auckland",
     "Active": true,
      "Mail": true
   }
 ],
 "ContactsMapping": [
   { "Source": "LinkKey", "Target": "ImportLinkID", "Type": "int" },
   { "Source": "First", "Target": "FirstName", "Type": "string" },
   { "Source": "Last", "Target": "LastName", "Type": "string" },
   { "Source": "Email", "Target": "EmailAddress", "Type": "string" },
   { "Source": "City", "Target": "City", "Type": "string" },
   { "Source": "Active", "Target": "ActiveFlag", "Type": "bool" },

    { "Source": "Mail", "Target": "OKToContact", "Type": "bool" }
 ],

 "Attributes": [
   {
     "LinkKey": 2005,
     "Type": "Region",
     "Attribute": "North",
     "Status": "Active",
     "Start": "2025-10-01",
     "End": null,
     "Group": "Geo"
   },
   {
     "LinkKey": 2005,
     "Type": "Membership",
     "Attribute": "Gold",
     "Status": "Active",
     "Start": "2026-01-01",
     "End": null,
     "Group": "Program"
   }
 ],
 "AttributesMapping": [
   { "Source": "LinkKey", "Target": "ImportLinkID", "Type": "int" },
   { "Source": "Type", "Target": "AttributeType", "Type": "string" },
   { "Source": "Attribute", "Target": "Attribute", "Type": "string" },
   { "Source": "Status", "Target": "Status", "Type": "string" },
   { "Source": "Start", "Target": "StartDate", "Type": "date" },
   { "Source": "End", "Target": "EndDate", "Type": "date" },
   { "Source": "Group", "Target": "AttributeGroup", "Type": "string" }
 ],

 "Notes": [
   {
     "LinkKey": 2005,
     "Email": "jordan.lee@example.org",
     "Type": "General",
     "Note": "Called on Tuesday",
     "Date": "2026-01-12",
     "Subject": "Follow-up",
     "Security": "Public"
   }
 ],
 "NotesMapping": [
   { "Source": "LinkKey", "Target": "ImportLinkID", "Type": "int" },
   { "Source": "Email", "Target": "EmailAddress", "Type": "string" },
   { "Source": "Type", "Target": "NoteType", "Type": "string" },
   { "Source": "Note", "Target": "ActualNote", "Type": "string" },
   { "Source": "Date", "Target": "NoteDate", "Type": "date" },
   { "Source": "Subject", "Target": "Subject", "Type": "string" },
   { "Source": "Security", "Target": "NoteSecurityType", "Type": "string" }
 ]
}

Scenario C: Contact + RecurringPayments + RecurringPaymentAttributes + RecurringPaymentDistributions linked by ImportLinkID

{
 "InstanceDesc": "Import run - Recurring payments",
 "Contacts": [
   {
     "LinkKey": 3009,
     "First": "Sam",
     "Last": "Nguyen",
     "Email": "sam.nguyen@example.net",
     "Mobile": "022345678",
     "Active": true,
      "Mail": true
   }
 ],
 "ContactsMapping": [
   { "Source": "LinkKey", "Target": "ImportLinkID", "Type": "int" },
   { "Source": "First", "Target": "FirstName", "Type": "string" },
   { "Source": "Last", "Target": "LastName", "Type": "string" },
   { "Source": "Email", "Target": "EmailAddress", "Type": "string" },
   { "Source": "Mobile", "Target": "MobilePhone", "Type": "string" },

    { "Source": "Active", "Target": "ActiveFlag", "Type": "bool" },
    { "Source": "Mail", "Target": "OKToContact", "Type": "bool" }
 ],

 "RecurringPayments": [
   {
     "LinkKey": 3009,
     "PayType": "Card",
     "Amount": "25.00",
     "Campaign": "Supporter Program",
     "Distribution": "General Fund",
     "Frequency": "Monthly",
     "Start": "2026-01-01",
     "Token": "tok_abc123",
     "Reference": "RP-3009-0001"
   }
 ],
 "RecurringPaymentsMapping": [
   { "Source": "LinkKey", "Target": "ImportLinkID", "Type": "int" },
   { "Source": "PayType", "Target": "PayType", "Type": "string" },
   { "Source": "Amount", "Target": "DonationAmt", "Type": "decimal" },
   { "Source": "Campaign", "Target": "Campaign", "Type": "string" },
   { "Source": "Distribution", "Target": "Distribution", "Type": "string" },
   { "Source": "Frequency", "Target": "Frequency", "Type": "string" },
   { "Source": "Start", "Target": "StartDate", "Type": "date" },
   { "Source": "Token", "Target": "Token", "Type": "string" },
   { "Source": "Reference", "Target": "Reference", "Type": "string" }
 ],

 "RecurringPaymentAttributes": [
   {
     "LinkKey": 3009,
     "Type": "Channel",
     "Attribute": "Web",
     "Value": "Yes",
     "Start": "2026-01-01",
     "RecurringRef": "RP-3009-0001",
     "Group": "Meta"
   }
 ],
 "RecurringPaymentAttributesMapping": [
   { "Source": "LinkKey", "Target": "ImportLinkID", "Type": "int" },
   { "Source": "Type", "Target": "AttributeType", "Type": "string" },
   { "Source": "Attribute", "Target": "Attribute", "Type": "string" },
   { "Source": "Value", "Target": "AttributeValue", "Type": "string" },
   { "Source": "Start", "Target": "Startdate", "Type": "date" },
   { "Source": "RecurringRef", "Target": "RecurringReference", "Type": "string" },
   { "Source": "Group", "Target": "AttributeGroup", "Type": "string" }
 ],

 "RecurringPaymentDistributions": [
   {
     "LinkKey": 3009,
     "Amount": "15.00",
     "Campaign": "Supporter Program",
     "Action": "Donation",
     "Category": "General",
     "Product": "Membership",
     "RecurringRef": "RP-3009-0001",
     "DocumentName": "Welcome Pack",
     "EmailReceipt": true
   },
   {
     "LinkKey": 3009,
     "Amount": "10.00",
     "Campaign": "Supporter Program",
     "Action": "Donation",
     "Category": "Special Project",
     "RecurringRef": "RP-3009-0001",
     "Product": "Project A",
     "EmailReceipt": false
   }
 ],
 "RecurringPaymentDistributionsMapping": [
   { "Source": "LinkKey", "Target": "ImportLinkID", "Type": "int" },
   { "Source": "Amount", "Target": "Amount", "Type": "decimal" },
   { "Source": "Campaign", "Target": "Campaign", "Type": "string" },
   { "Source": "Action", "Target": "CampaignAction", "Type": "string" },
   { "Source": "Category", "Target": "Category", "Type": "string" },
   { "Source": "Product", "Target": "Product", "Type": "string" },
   { "Source": "RecurringRef", "Target": "RecurringReference", "Type": "string" },
   { "Source": "DocumentName", "Target": "DocumentName", "Type": "string" },
   { "Source": "EmailReceipt", "Target": "EmailReceipt", "Type": "bool" }
 ]
}


Example successful response: { "ImportInstanceID": 12345, "ContactsInserted": 2, "ContactsFailed": 0, "ContactErrors": [], "PaymentsInserted": 1, "PaymentsFailed": 0, "PaymentErrors": [], "ContactMatching": { "MatchedContacts": 2, "NotMatchedContacts": 0 } }

Notes:
•    You can include any subset of sections; omitted sections are ignored.
•    If InstanceDesc is provided, a new import instance ID is created and returned.
 

POST /api/Import/ExecuteImportAndReport

POST /api/Import/ExecuteImportAndReport Purpose:
•    Executes the previously staged import and returns a summary/report payload.

Headers:
•    Content-Type: application/json
•    Authorization: Basic <base64(user:password)>
Body: { "ImportInstanceID": 12345 }

Response:
•    JSON report returned by ExecuteImportAndReportAsync, typically including processed counts, failures, and error details per entity type.
 

Common errors:
•    400 Missing or invalid body: ensure InstanceDesc/mappings are valid in ImportWithMapping; ensure ImportInstanceID > 0 in ExecuteImportAndReport.
•    401 Invalid credentials: Basic auth must be provided; the service uses the current principal’s identity as ownerID.
 

Postman quick setup:
•    Authorization tab: Type = Basic Auth, Username = your API username, Password = your API password.
•    Headers: Content-Type = application/json.
•    Body tab: raw JSON, paste examples above.
•    Send requests to your API base URL, e.g., https://api.vega.works/api/Import/ImportWithMapping and https://api.vega.works/api/Import/ExecuteImportAndReport.
 

Import File Schema:

{
 "Contacts": [
   {
     "ImportLinkID": 0,
     "ScoperID": "",
     "Title": "",
     "FirstName": "",
     "Middlename": "",
     "LastName": "",
     "Suffix": "",
     "Organisation": "",
     "JobTitle": "",
     "Salutation": "",
     "Address1": "",
     "Address2": "",
     "Address3": "",
     "Suburb": "",
     "City": "",
     "StateName": "",
     "Country": "",
     "PostCode": "",
     "EmailAddress": "",
     "Email2": "",
     "MobilePhone": "",
     "MainPhone": "",
     "WorkPhone": "",
     "JoinDate": "",
     "ActiveFlag": false,
     "OKToContact": false,
     "Membership": "",
     "AlertNote": "",
     "AttributeType1": "",
     "Attribute1": "",
     "AttributeType2": "",
     "Attribute2": "",
     "MatchEntityID": 0,
     "DPID": 0,
     "EntityStatusReason": "",
     "MailStatusReason": "",
     "InactiveDate": "",
     "DeceasedDate": "",
     "BirthDate": "",
     "EntityGuid": "",
     "AddressType": "",
     "Website": "",
     "Gender": "",
     "AccountName": "",
     "SourceCampaign": "",
     "AddressRound": "",
     "AddressSequence": "",
     "EntityCategory": "",
     "AttributeGroup1": "",
     "AttributeGroup2": "",
     "AttributeValue1": "",
     "AttributeValue2": "",
     "Branch": "",
     "AttributeType3": "",
     "Attribute3": "",
     "AttributeValue3": "",
     "AttributeComment1": "",
     "AttributeComment2": "",
     "AttributeComment3": "",
     "AttributeStartDate3": "",
     "HomePhone": ""
   }
 ],
 "Payments": [
   {
     "ImportLinkID": 0,
     "BatchCode": "",
     "PaymentDate": "",
     "Amount": 0.0,
     "PaymentStatus": "",
     "Campaign": "",
     "Category": "",
     "Appeal": "",
     "PaymentType": "",
     "Bank": "",
     "Branch": "",
     "Account": "",
     "PayDetails": "",
     "GiftFromID": 0,
     "GiftFromFirstName": "",
     "GiftFromLastName": "",
     "GiftFromEmailAddress": "",
     "ReceiptNo": "",
     "ReceiptDate": "",
     "PledgeAmount": 0.0,
     "AccountName": "",
     "Token": "",
     "Particulars": "",
     "Reference": "",
     "Code": "",
     "RecurrenceReference": "",
     "IsSupporterLed": false,
     "FundraiserLinkID": 0,
     "TeamLinkID": 0,
     "Trans_ID": 0,
     "Line_ID": 0,
     "DocumentName": "",
     "EmailReceipt": false,
     "Quantity": 0,
     "Product": "",
     "TicketNoFrom": "",
     "TicketNoTo": "",
     "ProductDonationAmount": 0.0,
     "PgReference": ""
   }
 ],
 "Attributes": [
   {
     "ImportLinkID": 0,
     "AttributeType": "",
     "Attribute": "",
     "StartDate": "",
     "EndDate": "",
     "Status": "",
     "AttributeValue": "",
     "AttributeGroup": "",
     "AttributeComment": "",
     "AssociatedCampaignHeader": "",
     "AssociatedCampaignAction": ""
   }
 ],
 "Lists": [
   {
     "ImportLinkID": 0,
     "ListName": ""
   }
 ],
 "Notes": [
   {
     "ImportLinkID": 0,
     "NoteType": "",
     "ActualNote": "",
     "NoteDate": "",
     "Subject": "",
     "UserEmail": "",
     "NoteSecurityType": ""
   }
 ],
 "PaymentAttributes": [
   {
     "ImportLinkID": 0,
     "AttributeGroup": "",
     "AttributeType": "",
     "Attribute": "",
     "AttributeValue": "",
     "Startdate": "",
     "PaymentReference": ""
   }
 ],
 "PaymentDistributions": [
   {
     "ImportLinkID": 0,
     "PaymentReference": "",
     "Amount": 0.0,
     "Campaign": "",
     "CampaignAction": "",
     "Category": "",
     "Quantity": 0,
     "Product": "",
     "TicketNoFrom": 0,
     "PaymentType": "",
     "DocumentName": "",
     "EmailReceipt": false
   }
 ],
 "RecurringPaymentAttributes": [
   {
     "ImportLinkID": 0,
     "AttributeType": "",
     "Attribute": "",
     "AttributeValue": "",
     "Startdate": "",
     "RecurringReference": "",
     "RecurringPaymentID": 0
   }
 ],
 "RecurringPaymentDistributions": [
   {
     "ImportLinkID": 0,
     "RecurringReference": "",
     "Amount": 0.0,
     "Campaign": "",
     "CampaignAction": "",
     "Category": "",
     "Quantity": 0,
     "Product": "",
     "DocumentName": "",
     "EmailReceipt": false,
     "RecurringPaymentID": 0
   }
 ],
 "RecurringPayments": [
   {
     "ImportLinkID": 0,
     "PayType": "",
     "DonationAmt": 0.0,
     "CardName": "",
     "CardNumber": "",
     "Campaign": "",
     "Distribution": "",
     "Frequency": "",
     "StartDate": "",
     "Token": "",
     "EndDate": "",
     "Status": "",
     "Particulars": "",
     "Code": "",
     "Reference": "",
     "PayBank": "",
     "PayBranch": "",
     "Expiry": "",
     "DueDate": "",
     "Appeal": "",
     "RecruitedBy": "",
     "PayDetails": "",
     "RecurringPaymentID": 0
   }
 ],
 "ContactsMapping": [
   {
     "Source": "",
     "Target": "",
     "Type": "string",
     "IsIdentity": false
   }
 ],
 "PaymentsMapping": [
   {
     "Source": "",
     "Target": "",
     "Type": "string",
     "IsIdentity": false
   }
 ],
 "AttributesMapping": [
   {
     "Source": "",
     "Target": "",
     "Type": "string",
     "IsIdentity": false
   }
 ],
 "ListsMapping": [
   {
     "Source": "",
     "Target": "",
     "Type": "string",
     "IsIdentity": false
   }
 ],
 "NotesMapping": [
   {
     "Source": "",
     "Target": "",
     "Type": "string",
     "IsIdentity": false
   }
 ],
 "PaymentAttributesMapping": [
   {
     "Source": "",
     "Target": "",
     "Type": "string",
     "IsIdentity": false
   }
 ],
 "PaymentDistributionsMapping": [
   {
     "Source": "",
     "Target": "",
     "Type": "string",
     "IsIdentity": false
   }
 ],
 "RecurringPaymentAttributesMapping": [
   {
     "Source": "",
     "Target": "",
     "Type": "string",
     "IsIdentity": false
   }
 ],
 "RecurringPaymentDistributionsMapping": [
   {
     "Source": "",
     "Target": "",
     "Type": "string",
     "IsIdentity": false
   }
 ],
 "RecurringPaymentsMapping": [
   {
     "Source": "",
     "Target": "",
     "Type": "string",
     "IsIdentity": false
   }
 ],
 "InstanceDesc": ""
}

Related articles

Comments

0 comments

Article is closed for comments.

Powered by Zendesk