API Call Samples

We reserve the right to log and verify your API calls and to contact you if we detect abuse on your part. For example:
  • the requests takes too long to return
  • the requests return too much data at a time
  • The requests are too frequent
We strongly suggest using the date filter parameters to return only the data that is relevant.

Select category  

Select function  

Function Details
Name Guid Required Description
SaveTask True Creates a task if no TaskId is specified or updates an existing task when a valid TaskId is specified.

Code Sample (Visual Basic, Dotnet Framework 4.x):
Public Class Sample
	
	Public Sub CodeSample_savetask()
		Dim params = New NameValueCollection From {
					{"fct", "savetask"},
					{"guid", "###"},
					{"projectid", "NULL"},
					{"taskid", "NULL"},
					{"tasknumber", "NULL"},
					{"summary", "NULL"},
					{"statusid", "NULL"},
					{"percentdone", "NULL"},
					{"groupid", "NULL"},
					{"typeid", "NULL"},
					{"priorityid", "NULL"},
					{"weekendallowed", "NULL"},
					{"estimatedhours", "NULL"},
					{"estimatedexpenses", "NULL"},
					{"dividehours", "NULL"}
		}

		Dim jsonText = apiCall(params)

		' https://www.newtonsoft.com/json suggested for JSON parsing to DotNet framework 4.x
		Dim jsonObj = Newtonsoft.Json.Linq.JObject.Parse(jsonText)

		Dim success = jsonObj.Item("status").ToString <> "fail"
		Dim jResults = DirectCast(jsonObj.Item("results"), Newtonsoft.Json.Linq.JArray)

		
	End Sub
	    
	Function apiCall(_param As NameValueCollection) As String

		Dim wc As New System.Net.WebClient With {
			.Encoding = System.Text.Encoding.UTF8
		}

		' may be needed on some machines
		Net.ServicePointManager.SecurityProtocol = CType(Net.SecurityProtocolType.Tls12, Net.SecurityProtocolType)

		_param.Item("format") = "iso8601" ' json, with dates formatted as ISO8601 string

		Dim responseBytes = wc.UploadValues("https://api.aceproject.com", "POST", _param)
		Return System.Text.Encoding.UTF8.GetString(responseBytes)

	End Function

End Class

Parameter Details
Name DataType Is Nullable Max length Domain Values Default Value Is Required
(Insert)
Is Required
(Update)
Is Required Description
Guid String False True Unique identifier for the authenticated user. The GUID has an expiry date and time which is managed automatically by the API.
ProjectId Integer True NULL True False Auto-generated unique identifier of a project.
TaskId Integer True NULL False True Auto-generated unique identifier of a task.
TaskNumber Decimal True Greater or equal to 0 NULL True False Unique number given to a task. The number must be unique within the project.
Summary String True 100 NULL True False Task summary.
Details String True NULL False Task details. Used with IsDetailsPlainText. When IsDetailsPlainText is true, any HTML formatting provided for the details field will be encoded.
StatusId Integer True NULL True False Auto-generated unique identifier of a task status.
PercentDone Integer True 0 to 10 NULL True False Percentage done value of the task. Must be 0 when task status type is waiting or 10 when task status type is completed.
GroupId Integer True NULL True False Auto-generated unique identifier of a task group.
TypeId Integer True NULL True False Auto-generated unique identifier of a task type.
PriorityId Integer True NULL True False Auto-generated unique identifier of a task priority.
WeekendAllowed Boolean True True or False NULL True False For projects that do not include weekends, this parameter indicates whether the task includes weekends as working days.
EstimatedStartDate DateTime True NULL False Estimated start date.
EstimatedDueDate DateTime True NULL False Estimated end date.
EstimatedHours Decimal True Greater or equal to 0 NULL True False Estimated hours.
EstimatedExpenses Decimal True Greater or equal to 0 NULL True False Estimated expenses. This parameter is ignored if cost tracking is disabled for the account.
ManageActualDates Boolean True True or False NULL True
ActualStartDate Date True NULL False Actual start date.
ActualDueDate Date True NULL False Actual end date.
AddComments String True NULL False Text of a comment to add to a task. When IsCommentsPlainText is true, any HTML formatting provided for the comments field will be encoded.
DivideHours Boolean True True or False NULL True False Indicates whether to divide hours amongst users assigned to the task.
Notify Boolean True True or False NULL True Indicates whether to send email notifications.
IsDetailsPlainText Boolean True True or False NULL True When true, any HTML formatting provided for the details field will be encoded.
IsCommentsPlainText Boolean True True or False NULL False When true, any HTML formatting provided for the addcomments field will be encoded.
GetTaskInReturn Boolean True True or False NULL False Indicates whether to return the task information to the caller (avoids calling GetTask after saving or updating a task).
MarkLevel Boolean True True or False NULL False Indicates whether to mark the task for the caller.
FileInfo String True NULL True
Format String False RS: RecordSet
DS: DataSet
JSON: JSON
DS True Return Format