The Form Submission API returns all transactions from a given form and specified date range. Data including billing info, authentication, and gift recipients will be excluded. This API will return results paginated, up to 200 transactions a page. You are able to specify the page number in the API (see below).
Base Resource URI
For Production, use:
https://ows.omeda.com/webservices/rest/brand/{brandAbbreviation}/formbuilder/registration/site/{site_context}/startdate/{mmddyyyy}/enddate/{mmddyyyy}/*
or with page number:
https://ows.omeda.com/webservices/rest/brand/{brandAbbreviation}/formbuilder/registration/site/{site_context}/startdate/{mmddyyyy}/enddate/{mmddyyyy}/page/{pagenumber}/*
For Testing, use: https://ows.omedastaging.com/webservices/rest/brand/{brandAbbreviation}/formbuilder/registration/site/{site_context}/startdate/{mmddyyyy}/enddate/{mmddyyyy}/*
or with page number:
https://ows.omedastaging.com/webservices/rest/brand/{brandAbbreviation}/formbuilder/registration/site/{site_context}/startdate/{startdate}/enddate/{enddate}/page/{pagenumber}/*
brandAbbreviation is the abbreviation for the brand. site_context is the specific form for which we are requesting transactions from. Example: https://sample.dragonforms.com/omeda_new startdate is the start of the date range of when transactions were made from the specified form. enddate is the end of the date range of when transactions were made from the specified form. This cannot exceed greater than 16 days from the startdate.
*Note – formatting for either date value is MMddyyyy or MMddyyyy_HHmm with the hours and minutes (on a 24 hour clock) being optional. For example, January 2, 2023 1:23 PM would be formatted as 01022023_1323. If you use MMddyyyy without the hours and minutes, then enddate must be prior to the current date. If using MMddyyyy_HHmm (with hours and minutes), you can use current date as the enddate but with a time prior to current time.
HTTP Headers
The HTTP header must contain the following element: x-omeda-appid a unique id provided to you by Omeda to access your data. The request will fail without a valid id.
Content Type
The content type is application/json. JSONapplication/json
JSON is the preferred data exchange format, because it is lightweight and, in most cases, faster to process and utilizes less bandwidth. There are many available open-source JSON libraries available. See json.org for details.
Supported HTTP Methods
There is one HTTP method supported: GET : See W3C’s GET specs for details.
Field Definition
The following table describes the data elements present on the response from the API.
Form Submission Return Elements
Attribute Name
Data Type
Description
FormTransactions
JSON Array
JSON element containing multiple Form Transaction Elements elements (see below)
PageSummary
String
Defines which page number of results are displayed out of total number pages of results. Each page will display up to 200 transactions.
SubmissionID
String
A unique identifier for the web services response. It can be used to cross-reference the response in Omeda’s database.
Form Transactions Return Elements
Attribute Name
Data Type
Description
FormData
JSON Array
JSON element containing multiple Form Data Elements elements (see below)
Form Data Return Elements
Attribute Name
Data Type
Description
Addresses
JSON Array
JSON element containing multiple Addresses elements (see below)
CustomerDemographics
JSON Array
JSON element containing multiple Customer Demographics elements (see below)
CustomerStatusId
Integer
Status of the customer record: 0=deleted, 1=active, 3=test.
Emails
JSON Array
JSON element containing multiple Emails elements (see below)
Filters
JSON Array
JSON element containing multiple Filters elements (see below)
FirstName
String
First name of customer, up to 100 characters long.
LastName
String
Last name of customer, up to 100 characters long.
Products
JSON Array
JSON element containing multiple Products elements (see below)
SessionId
String
A unique identifier for the web services response. It can be used to cross-reference the response in Omeda’s database.
SiteId
Integer
A unique identifier for the specified form.
Title
String
Job title, up to 100 characters long.
FormSubmissionDate
Date
Date and time of when the form submission was made. yyyy-mm-dd hh:mm:ss
Addresses Return Elements
Attribute Name
Data Type
Description
AddressProducts
Integer
Comma-separated list of product ids to associate this address.
ApartmentMailStop
String
Apartment, mail stop or suite number, up to 255 characters long.
Company
String
Company name, up to 255 characters long.
PostalCode
String
ZIP code or postal code.
RegionCode
String
For country_code=’USA’ or ‘CAN’, a 2-character US state or Canadian code used by the postal service. Omeda also has region codes for other countries of the world.
Street
String
First line of street address, up to 255 characters long.
Customer Demographics Return Elements
Attribute Name
Data Type
Description
OmedaDemographicId
Integer
Identifier that specifies the explicit omeda demographic ID.
OmedaDemographicValue
Integer
The value id that is associated with the OmedaDemographicId provided above selected by the customer.
Emails Return Elements
Attribute Name
Data Type
Description
EmailAddress
String
Email Address associated to the Form Data transaction.
EmailProducts
String
Comma-separated list of product ids to associate this email address.
Filters Return Elements
Attribute Name
Data Type
Description
DeploymentTypeOptIn
JSON Array
JSON element containing multipleDeploymentTypeOptIn elements (see below)
DeploymentTypeOptOut
JSON Array
JSON element containing multipleDeploymentTypeOptOut elements (see below)
DeploymentTypeOptIn Return Elements
Attribute Name
Data Type
Description
DeploymentTypeId
String
The deployment type for which the opt-in is requested.
EmailAddress
String
The customer’s email address for which the deployment type opt-in is requested.
PromoCode
String
Promo Code tied to the opt-in requested.
DeploymentTypeOptOut Return Elements
Attribute Name
Data Type
Description
DeploymentTypeId
String
The deployment type for which the opt-out is requested.
EmailAddress
String
The customer’s email address for which the deployment type opt-out is requested.
PromoCode
String
Promo Code tied to the opt-out requested.
Product Return Elements
Attribute Name
Data Type
Description
OmedaProductId
Integer
Omeda product id for the product being requested. Magazines (productType=1), Newsletters (productType=2), etc. See list of all Product Types here.
Recieve
Integer
1 = opt-in, 0 = opt-out. Assumed to be 1 if not given. Explicitly allows this order service to capture opt-out behaviors as part of the order transaction.
RequestedVersion
String
Applicable only for products that have different versions (‘P’ for print, ‘D’ for digital, ‘B’ for both).
Response
HTTP Response Codes
Status
Description
200 OK
The request has succeeded. See Example Response below.
400 Bad Request
This response will be returned when Start or End Dates are invalid. Either future dates are inputted, End Date is prior to Start Date, or the date range exceeds more than 2 days.
403 Forbidden
Typically, this error occurs when the credentials are erroneous. Potentially, an incorrect x-omeda-appid.
404 Not Found
This response occurs when the form submitted was not found.
500 Internal Server Error
In the rare case that there is a server-side problem, this response will be returned. This generally indicates a problem of a more serious nature, and submitting additional requests may not be advisable. Please contact your Omeda Account Representative if the issue continues.
Successful Submission
A successful submission will return Form Submission data from the given form and date range.
