POST api/institutions/lead-update

Back to API Documentation

The Lead Update service is located at https://partners.educationdynamics.com/api/Institutions/lead-update. The posting service can be called using HTTP POST and will return a JSON-formatted response indicating the success or failure of the partner’s submission, along with response messages when applicable. This endpoint updates an existing EMS lead. The request must include EMSInstitutionId and LookUpKeyList. LookUpKeyList determines which identifiers should be used to locate the existing lead. At least one valid lookup value must be supplied for the provided LookUpKeyList. If more than one lookup key is provided, the service will attempt to locate the lead using each lookup key until a matching lead is found.

Request Information

URI Parameters

None.

Body Parameters

Name	Description	Type
APIKey	Required \| Partner credentials. This value will be provided by the EDDY Account Management team.	globally unique identifier
ClientAdmitDate	Admit date.	string
ClientApplicationDate	Application date.	string
ClientApplicationDegreeName	Application degree name.	string
ClientApplicationDeniedDate	Application denied date.	string
ClientApplicationStartDate	Application start date.	string
ClientApplicationStartTerm	Application start term.	string
ClientApplicationSubmittedDate	Application submitted date.	string
ClientAppointmentDate	Appointment date.	string
ClientContactDate	Contact date.	string
ClientDepositDate	Deposit date.	string
ClientEnrollDate	Enrollment date.	string
ClientFAFSAReceivedDate	FAFSA received date.	string
ClientFirstTermPersistDate	First term persist date.	string
ClientGraduateDate	Graduation date.	string
ClientInitialStartTerm	Initial start term.	string
ClientInterviewDate	Interview date.	string
ClientNotes	Notes associated with the lead.	string
ClientQualifiedDate	Qualified date.	string
ClientRegistered	Registration status.	string
ClientStartDate	Start date.	string
ClientStartReceivedDate	Start received date.	string
ClientStatus	Current client status. Partners should map their statuses to the supported standardized client status values. Certain client statuses correspond to client date fields. If a supported ClientStatus is provided and the matching date field is not provided, the service may default that matching date to the current date when the lead does not already have a value for that date. Supported standardized status values: ApplicationsCompleted Interviews Starts Contacts Enrollments ApplicationsStarted Admit Appointment Qualifies Graduated Persists ApplicationSubmitted Deposit ApplicationsDenied	string
ClientStatusUpdatedDate	Status updated date.	string
ClosedReasonCode	Closed reason code. This should only be provided when LeadStateId is set to 2 (Closed). If LeadStateId is set to 2, ClosedReasonCode should also be provided.	string
CompletedApplicationChecklistItems	Completed application checklist items.	string
CustomFields	Additional custom field data. Preferred format is JSON.	string
Email	Email address. Required when LookUpKeyList includes EmailAddress, or when LookUpKeyList includes NameAndEmailorPhone and Phone is not provided.	string
EMSInstitutionId	Required \| EMS Institution Id. This value will be provided by the EDDY Account Management team.	integer
EMSLeadId	EMS Lead Id. Required when LookUpKeyList includes EMSLeadId.	decimal number
ExternalId	External lead identifier. Required when LookUpKeyList includes ExternalId.	string
FirstName	First name. Required when LookUpKeyList includes FirstLastName or NameAndEmailorPhone.	string
ISLeadId	IS Lead Id. Required when LookUpKeyList includes ISLeadId.	decimal number
LastName	Last name. Required when LookUpKeyList includes FirstLastName or NameAndEmailorPhone.	string
LeadStateId	Lead state id. Accepted values: 1 = Active 2 = Closed If LeadStateId is set to 2 (Closed), ClosedReasonCode should also be provided.	integer
LookUpKeyList	Required \| List of integer lookup keys used to locate the lead to update. Accepted values: 1 = ExternalId 4 = EmailAddress 6 = ISLeadId 7 = Phone1 8 = EMSLeadId 9 = FirstLastName 10 = NameAndEmailorPhone At least one corresponding lookup value must be supplied.	Collection of integer
PendingApplicationChecklistItems	Pending application checklist items.	string
Phone	Phone number. Required when LookUpKeyList includes Phone1, or when LookUpKeyList includes NameAndEmailorPhone and Email is not provided.	string

Request Format

Conten-Type: application/json

            {
               "apiKey": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
               "emsInstitutionId": XXX,
               "lookUpKeyList": [1,4],
               "externalId": "ABC123",
               "email": "[email protected]",
               "clientApplicationDegreeName": "Bachelor of Science",
               "customFields": "{\"FieldName\":\"FieldValue\"}",
               "clientRegistered": "Yes",
               "clientNotes": "Updated client notes.",
               "clientStatus": "ApplicationsCompleted",
               "clientApplicationStartTerm": "Fall 2026",
               "pendingApplicationChecklistItems": "Transcript, FAFSA",
               "clientApplicationDate": "2026-05-06",
               "clientStatusUpdatedDate": "2026-05-06"
             }

Response Information

Output

        Successfully updated leads will return with an "IsSuccessful" value of true.
             The "Body" may include lead update context such as EMSInstitutionId and LeadGUID when available.
             The "Messages" collection will include one or more response messages from the API message configuration.
            
             Example successful response:
             {
               "IsSuccessful": true,
               "Body": {
                 "EMSInstitutionId": 1234,
                 "LeadGUID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
               },
               "ResponseDateTime": "2026-05-08T14:39:28.1899614-04:00",
               "RequestDateTime": "2026-05-08T14:39:28.1779627-04:00",
               "ResponseGuid": "b959696d-5bb5-4954-9bd6-d7cc3d981257",
               "Messages": [
                 {
                   "MessageCode": "msg0117",
                   "Message": "Lead update was submitted successfully."
                 }
               ],
               "TotalResponseTime": 0
             }
            
             If the lead is found but no update is needed, the response may return IsSuccessful as true with a Body value
             indicating "No Updates Needed" and a message explaining that the lead was found but no values changed.
            
             Validation errors will return a Bad Request response with "IsSuccessful" as false, "Body" as "ValidationFailed",
             and one or more messages explaining what needs to be corrected.
            
             Possible validation messages include:
             - EMSInstitutionId is required.
             - LeadStateId must be either 1 or 2 when provided.
             - LookUpKeyList is required.
             - Invalid lookup key.
             - At least one valid lookup value is required for the provided LookUpKeyList.
            
             Example validation failure response:
             {
               "IsSuccessful": false,
               "Body": "ValidationFailed",
               "ResponseDateTime": "2026-05-08T14:39:28.1899614-04:00",
               "RequestDateTime": "2026-05-08T14:39:28.1779627-04:00",
               "ResponseGuid": "b959696d-5bb5-4954-9bd6-d7cc3d981257",
               "Messages": [
                 {
                   "MessageCode": "msg0108",
                   "Message": "EMSInstitutionId is required."
                 },
                 {
                   "MessageCode": "msg0109",
                   "Message": "LeadStateId must be either 1 or 2 when provided."
                 },
                 {
                   "MessageCode": "msg0110",
                   "Message": "LookUpKeyList is required."
                 }
               ],
               "TotalResponseTime": 0
             }
            
             If no existing EMS lead can be found using the provided lookup keys, the response will return
             "IsSuccessful" as false, a Body value indicating "Lead Not Found", and a configured response message.
            
             If the lead update cannot be submitted to the lead service, the response will return
             "IsSuccessful" as false, a Body value indicating "Update Failed", and a configured response message.
            
             If an unexpected exception occurs while updating the lead, the response will return
             "IsSuccessful" as false and include a configured exception response message.